Get Files

Retrieve a paginated list of files for an organization

Get Files

Retrieve a paginated list of files for your organization with optional filtering by type and tags. This endpoint returns file metadata along with storage statistics.

Endpoint

GET /api/uploads/files

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

Query Parameters

Parameter	Type	Required	Default	Description
`type`	string	No	-	Filter files by type (`image`, `video`, `audio`)
`tags`	string	No	-	Comma-separated list of tags to filter by (e.g., `"short,video"`)
`limit`	string	No	`"50"`	Number of files to return per page (1-100)
`offset`	string	No	`"0"`	Number of files to skip for pagination

Request Example

# List all files (first page)
curl -X GET "https://api.swiftia.io/api/uploads/files?limit=20&offset=0"

# Filter by type
curl -X GET "https://api.swiftia.io/api/uploads/files?type=video&limit=50"

# Filter by tags
curl -X GET "https://api.swiftia.io/api/uploads/files?tags=short,cropped&limit=30"

# Combined filters with pagination
curl -X GET "https://api.swiftia.io/api/uploads/files?type=video&tags=short&limit=20&offset=40"

Response

Success Response (200)

{
  "subSize": 1000,
  "usedSize": 750.5,
  "usedSizePercent": 75.05,
  "files": [
    {
      "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"
    },
    {
      "id": "file_124",
      "name": "background-image.jpg",
      "type": "image",
      "size": 524288,
      "length": 0,
      "status": "completed",
      "description": "Background image for video",
      "tags": ["background"],
      "jobId": null,
      "url": "https://storage.swiftia.io/media/files/org_123/file_124.jpg",
      "thumbnailUrl": null,
      "createdAt": "2024-01-15T09:15:00Z"
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

Response Fields

Field	Type	Description
`subSize`	number	Total storage size allocated to your organization (in MB)
`usedSize`	number	Current storage usage (in MB)
`usedSizePercent`	number	Percentage of storage used (0-100)
`files`	array	Array of file objects
`total`	number	Total number of files matching the filters (before pagination)
`limit`	number	Number of files per page
`offset`	number	Number of files skipped

File Object Fields

Field	Type	Description
`id`	string	Unique identifier for the file
`name`	string	Original filename
`type`	string	File type (`image`, `video`, `audio`)
`size`	number	File size in bytes
`length`	number	Duration/length (for video/audio files, in seconds). Defaults to 0 if not applicable
`status`	string	File status (`completed`, `pending`)
`description`	string \| null	Optional description of the file
`tags`	array	Array of tags associated with the file
`jobId`	string \| null	ID of the job that created this file (if applicable)
`url`	string	Public URL to access the file
`thumbnailUrl`	string \| null	URL to the file's thumbnail (for videos)
`createdAt`	string	ISO 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

Invalid pagination parameters:

{
  "message": "Limit must be between 1 and 100"
}

Or:

{
  "message": "Offset must be a non-negative number"
}

Or missing organization:

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

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

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

500 Internal Server Error

{
  "error": "Internal server error"
}

Pagination

The endpoint supports pagination using limit and offset parameters:

limit: Number of files per page (default: 50, maximum: 100)
offset: Number of files to skip (default: 0)

Pagination Example

# First page (files 1-20)
GET /api/uploads/files?limit=20&offset=0

# Second page (files 21-40)
GET /api/uploads/files?limit=20&offset=20

# Third page (files 41-60)
GET /api/uploads/files?limit=20&offset=40

Calculating Total Pages

Use the total field in the response to calculate total pages:

const totalPages = Math.ceil(response.total / response.limit);

Filtering

Filter by Type

Filter files by their type (image, video, or audio):

# Get only video files
GET /api/uploads/files?type=video

# Get only image files
GET /api/uploads/files?type=image

# Get only audio files
GET /api/uploads/files?type=audio

Filter by Tags

Filter files by tags using a comma-separated list:

# Files with "short" tag
GET /api/uploads/files?tags=short

# Files with "short" OR "cropped" tags
GET /api/uploads/files?tags=short,cropped

Note: The tag filter uses OR logic - files matching any of the specified tags will be returned.

Combined Filters

You can combine type and tag filters:

# Video files with "short" tag
GET /api/uploads/files?type=video&tags=short

Storage Information

The response includes storage statistics:

subSize: Your organization's total storage allocation (in MB)
usedSize: Current storage usage (in MB)
usedSizePercent: Percentage of storage used

Storage Limits by Plan

Plan	Storage Limit
Free	100 MB
Pro	1,000 MB (1 GB)
Swift	10,000 MB (10 GB)

Example Use Cases

List All Video Files

curl -X GET "https://api.swiftia.io/api/uploads/files?type=video"

Get Files with Specific Tags

curl -X GET "https://api.swiftia.io/api/uploads/files?tags=short,cropped"

Paginated File Listing

async function getAllFiles(apiKey) {
  const files = [];
  let offset = 0;
  const limit = 50;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.swiftia.io/api/uploads/files?limit=${limit}&offset=${offset}`,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`
        }
      }
    );

    const data = await response.json();
    files.push(...data.files);

    hasMore = offset + limit < data.total;
    offset += limit;
  }

  return files;
}

Rate Limiting

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

Get File - Get details of a specific file
Delete File - Delete a file from storage

Get Files

On this page