Files

Manage individual file assets

Get all files for a project

Retrieves a paginated list of all files associated with the current project. Files can be filtered using query parameters.

GET
/files

Authorization

AuthorizationRequiredBearer <token>

Requires a Bearer token in the Authorization header. Format: Authorization: Bearer YOUR_API_KEY

In: header

Query Parameters

pageinteger

Page number

Default: 1Minimum: 1
limitinteger

Items per page

Default: 20Minimum: 1Maximum: 100

Response Body

A paginated list of files.

TypeScript Definitions

Use the response body type in TypeScript.

metaobject
dataarray<object>
linksobject
curl -X GET "https://api.ittybit.com/files?page=1&limit=20" \
  -H "Authorization: Bearer <token>"
{
  "meta": {
    "id": "req_listFiles123",
    "status": 200,
    "object": "list",
    "total": 1,
    "page": 1,
    "limit": 20,
    "pages": 1
  },
  "data": [
    {
      "id": "file_abc123",
      "media_id": "med_xyz456",
      "object": "source",
      "kind": "video",
      "format": "mp4",
      "type": "video/mp4",
      "filesize": 1024000,
      "filename": "example.mp4",
      "url": "https://my-project.ittybit.net/files/example.mp4",
      "created": "2023-01-01T00:00:00Z",
      "updated": "2023-01-01T00:00:00Z"
    }
  ],
  "links": {
    "self": "/files?page=1"
  }
}

Create a new file record from a URL

Registers a file from a publicly accessible URL. The file will be ingested asynchronously.

POST
/files

Authorization

AuthorizationRequiredBearer <token>

Requires a Bearer token in the Authorization header. Format: Authorization: Bearer YOUR_API_KEY

In: header

Request Body

application/jsonRequired

Details of the file to create, including the source URL and optional metadata.

urlRequiredstring

The publicly accessible URL of the file to ingest.

Format: "uri"
filenamestring

Optional desired filename. If not provided, it may be derived from the URL.

folderstring

Folder path (optional)

media_idstring

Optional existing media ID to associate the file with.

labelstring

Optional label for the file.

metadataobject

Optional user-defined key-value metadata.

asyncboolean

Whether to process the ingestion asynchronously.

Default: true

Response Body

File created successfully.

TypeScript Definitions

Use the response body type in TypeScript.

metaobject
dataobject
linksobject
curl -X POST "https://api.ittybit.com/files" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
    "filename": "bunny.mp4",
    "folder": "examples/cartoons",
    "metadata": {
      "credit": "gtv-videos-bucket"
    }
  }'
{
  "meta": {
    "id": "req_abcdefgh12345678",
    "type": "object"
  },
  "data": {
    "id": "file_abcdefgh12345678",
    "media_id": "med_abcdefgh12345678",
    "object": "source",
    "kind": "video",
    "format": "mp4",
    "type": "video/mp4",
    "filesize": 15482765,
    "filename": "bunny.mp4",
    "url": "https://my-project.ittybit.net/examples/cartoons/bunny.mp4",
    "status": "ready",
    "created": "2025-01-01T12:34:56Z",
    "updated": "2025-01-01T12:34:56Z"
  },
  "links": {
    "self": "https://api.ittybit.com/files/file_abcdefgh12345678"
  }
}

Get a specific file by ID

Retrieves detailed information about a specific file identified by its unique ID, including its metadata, media associations, and technical properties.

GET
/files/{id}

Authorization

AuthorizationRequiredBearer <token>

Requires a Bearer token in the Authorization header. Format: Authorization: Bearer YOUR_API_KEY

In: header

Path Parameters

idRequiredstring

Unique identifier of the file to retrieve. Must be a valid file ID (e.g., file_7bKpN2950Dx4EW8T).

Response Body

Returns the file details

TypeScript Definitions

Use the response body type in TypeScript.

metaobject
dataobject
linksobject
curl -X GET "https://api.ittybit.com/files/string" \
  -H "Authorization: Bearer <token>"

Demonstrates a successful response when retrieving a video file with all properties

{
  "meta": {
    "id": "req_xyz789abc123",
    "method": "GET",
    "url": "/files/file_7bKpN2950Dx4EW8T",
    "version": "2024-03-21",
    "status": 200,
    "org_id": "org_01J9QT9Q853B3P8PV33G8FR0YZ",
    "project_id": "proj_53mevg489TDc",
    "object": "file",
    "created": "2025-04-25T11:30:00.123Z"
  },
  "data": {
    "id": "file_7bKpN2950Dx4EW8T",
    "media_id": "med_63fe8P12r19KqBYM",
    "object": "source",
    "kind": "video",
    "format": "mp4",
    "type": "video/mp4",
    "width": 1920,
    "height": 1080,
    "duration": 120.5,
    "fps": 30,
    "filesize": 175158,
    "folder": "user_uploads/project_alpha",
    "filename": "customer-video-final.mp4",
    "url": "https://my-project.ittybit.net/user_uploads/project_alpha/customer-video-final.mp4",
    "created_by": "task_50de8d58NvXNyNrw",
    "created": "2024-03-21T15:33:12.456Z",
    "updated": "2024-03-21T15:33:12.456Z",
    "metadata": {
      "customer_id": "cust_123"
    },
    "analysis": null,
    "original": true
  },
  "links": {
    "self": "https://api.ittybit.com/files/file_7bKpN2950Dx4EW8T"
  }
}

Update file metadata

Updates metadata, filename, or folder properties of an existing file. Only the specified fields will be updated.

PATCH
/files/{id}

Authorization

AuthorizationRequiredBearer <token>

Requires a Bearer token in the Authorization header. Format: Authorization: Bearer YOUR_API_KEY

In: header

Request Body

application/jsonRequired

Fields to update on the file. Can include metadata properties, filename, and/or folder path.

metadataobject

An object containing key-value pairs to set or update. Set a key to null to remove it.

filenamestring

New filename for the file.

folderstring

New folder path for the file.

Path Parameters

idRequiredstring

Unique identifier of the file to update. Must be a valid file ID (e.g., file_abc123).

Response Body

File updated successfully.

TypeScript Definitions

Use the response body type in TypeScript.

metaobject
dataobject
linksobject
curl -X PATCH "https://api.ittybit.com/files/string" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "final_approved_video.mp4",
    "folder": "archive/2024"
  }'
{
  "meta": {
    "id": "req_updateFile789",
    "status": 200,
    "object": "file"
  },
  "data": {
    "id": "file_abc123",
    "media_id": "med_xyz456",
    "object": "source",
    "kind": "video",
    "format": "mp4",
    "type": "video/mp4",
    "filesize": 2048576,
    "filename": "final_approved_video.mp4",
    "folder": "archive/2024",
    "url": "https://my-project.ittybit.net/archive/2024/final_approved_video.mp4",
    "created": "2023-01-03T10:00:00Z",
    "updated": "2023-01-04T15:30:00Z"
  },
  "links": {
    "self": "/files/file_abc123"
  }
}

Delete a file

Permanently removes a file from the system. This action cannot be undone. Associated media entries may still reference this file ID.

DELETE
/files/{id}

Authorization

AuthorizationRequiredBearer <token>

Requires a Bearer token in the Authorization header. Format: Authorization: Bearer YOUR_API_KEY

In: header

Path Parameters

idRequiredstring

Unique identifier of the file to delete. Must be a valid file ID (e.g., file_7bKpN2950Dx4EW8T).

Response Body

Confirmation that the file was deleted successfully.

TypeScript Definitions

Use the response body type in TypeScript.

responseRequiredunknown
curl -X DELETE "https://api.ittybit.com/files/string" \
  -H "Authorization: Bearer <token>"
{
  "meta": {
    "id": "req_jkl012mno345",
    "status": 200,
    "object": "confirmation"
  },
  "data": {
    "message": "File file_7bKpN2950Dx4EW8T deleted successfully."
  },
  "links": {
    "self": "https://api.ittybit.com/files/file_7bKpN2950Dx4EW8T"
  }
}

Overview

Previous Page

List FilesGET

Next Page