Documentation

Get File

Retrieve detailed information about a specific file by its ID

Get File

Retrieve detailed information about a specific file by its ID. This endpoint returns complete file metadata including the public URL for accessing the file.

Endpoint

GET /api/uploads/files/{fileId}

Note: When using API key authentication, the organizationId query parameter is optional. The API automatically uses the organization associated with your API key.

Path Parameters

ParameterTypeRequiredDescription
fileIdstringYesUnique identifier of the file

Request Example

curl -X GET "https://api.swiftia.io/api/uploads/files/file_123"

Response

Success Response (200)

{
  "id": "file_123",
  "name": "my-video.mp4",
  "type": "video",
  "size": 15728640,
  "length": 120,
  "status": "completed",
  "description": null,
  "tags": ["short", "cropped"],
  "jobId": "job_456",
  "url": "https://storage.swiftia.io/media/files/org_123/file_123.mp4",
  "thumbnailUrl": "https://storage.swiftia.io/media/thumbnails/file_123.jpg",
  "createdAt": "2024-01-15T10:30:00Z"
}

Response Fields

FieldTypeDescription
idstringUnique identifier for the file
namestringOriginal filename
typestringFile type (image, video, audio)
sizenumberFile size in bytes
lengthnumberDuration/length (for video/audio files, in seconds). Defaults to 0 if not applicable
statusstringFile status (completed, pending)
descriptionstring | nullOptional description of the file
tagsarrayArray of tags associated with the file
jobIdstring | nullID of the job that created this file (if applicable)
urlstringPublic URL to access the file
thumbnailUrlstring | nullURL to the file's thumbnail (for videos)
createdAtstringISO 8601 timestamp when the file was created

Note: Internal fields (key, userId, organizationId) are excluded from the response for security and privacy.

Error Responses

400 Bad Request

{
  "message": "Organization ID is required"
}

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

{
  "message": "Organization ID mismatch. API key is bound to a different organization."
}

404 Not Found

{
  "message": "File not found"
}

This error occurs when:

  • The file ID doesn't exist
  • The file belongs to a different organization
  • The file has been deleted

500 Internal Server Error

{
  "error": "Internal server error"
}

Example Use Cases

Retrieve File Details

async function getFileDetails(apiKey, fileId) {
  const response = await fetch(
    `https://api.swiftia.io/api/uploads/files/${fileId}`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );

  if (!response.ok) {
    if (response.status === 404) {
      throw new Error('File not found');
    }
    throw new Error('Failed to retrieve file');
  }

  const file = await response.json();
  return file;
}

Check File Status

async function checkFileStatus(apiKey, fileId) {
  const file = await getFileDetails(apiKey, fileId);
  
  if (file.status === 'completed') {
    console.log(`File ${fileId} is ready: ${file.url}`);
  } else if (file.status === 'pending') {
    console.log(`File ${fileId} is still processing`);
  } else {
    console.log(`File ${fileId} failed to process`);
  }
  
  return file.status;
}

Get File URL

async function getFileUrl(apiKey, fileId) {
  const file = await getFileDetails(apiKey, fileId);
  return file.url;
}

Security Considerations

Organization Isolation

  • API keys are bound to specific organizations
  • You can only access files belonging to your organization
  • Attempting to access files from other organizations will result in a 404 error

Internal Fields Excluded

For security and privacy, the following internal fields are not included in the response:

  • key - Internal S3 storage key
  • userId - Internal user identifier
  • organizationId - Internal organization identifier

Only the public url field is provided for accessing files.

Rate Limiting

This endpoint is subject to rate limiting based on your subscription plan. Please refer to the Rate Limiting documentation for details.