Media

Manage media items (collections of files)

Media Objects

A media object is a collection of files. It can be used to store images, videos, or other files.

Endpoints

Get all media

Retrieves a list of all media for the current project

GET
/media

Authorization

AuthorizationRequiredBearer <token>

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

In: header

Query Parameters

pageinteger

Page number for pagination.

Default: 1Minimum: 1
limitinteger

Number of media items to return per page.

Default: 12Minimum: 1Maximum: 100

Response Body

A list of media items

TypeScript Definitions

Use the response body type in TypeScript.

metaobject
dataarray<object>
linksobject
curl -X GET "https://api.ittybit.com/media?page=1&limit=12" \
  -H "Authorization: Bearer <token>"
{
  "meta": {
    "id": "req_listMedia123",
    "status": 200,
    "object": "list",
    "total": 1,
    "page": 1,
    "limit": 12,
    "pages": 1
  },
  "data": [
    {
      "id": "med_abc123",
      "object": "media",
      "org_id": "org_01J9QT9Q853B3P8PV33G8FR0YZ",
      "project_id": "proj_53mevg489TDc",
      "live_mode": true,
      "kind": "video",
      "type": "video/mp4",
      "filename": "example.mp4",
      "sources": [
        {
          "id": "file_def456",
          "object": "source",
          "kind": "video",
          "format": "mp4",
          "type": "video/mp4",
          "filesize": 12582912,
          "original": true,
          "src": "https://my-project.ittybit.net/example.mp4",
          "filename": "example.mp4",
          "created": "2023-02-01T10:00:00Z",
          "updated": "2023-02-01T10:00:00Z"
        }
      ],
      "original": "https://my-project.ittybit.net/example.mp4",
      "status": "ready",
      "created": "2023-02-01T10:00:00Z",
      "updated": "2023-02-01T10:00:00Z"
    }
  ],
  "links": {
    "self": "/media?page=1"
  }
}

Create a new media item

Creates a new media item from a URL or as an empty placeholder

POST
/media

Authorization

AuthorizationRequiredBearer <token>

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

In: header

Request Body

application/jsonRequired

Information needed to create a new media item, either from a URL or as an empty placeholder.

urlstring

URL of the media file to ingest. Required unless 'empty' is true.

Format: "uri"
labelstring

Label for the media

folderstring

Folder to store the media in

filenamestring

Filename for the media

titlestring

Title for the media

metadataobject

Additional metadata for the media

asyncboolean

Whether to process the media asynchronously

Default: false
emptyboolean

Create an empty media placeholder

Default: false

Response Body

Media created successfully

TypeScript Definitions

Use the response body type in TypeScript.

metaobject
dataobject
linksobject
curl -X POST "https://api.ittybit.com/media" \
  -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_createMedia123",
    "status": 201,
    "object": "media"
  },
  "data": {
    "id": "med_newlyCreated",
    "object": "media",
    "org_id": "org_01J9QT9Q853B3P8PV33G8FR0YZ",
    "project_id": "proj_53mevg489TDc",
    "live_mode": true,
    "kind": "video",
    "type": "video/mp4",
    "filename": "escapes.mp4",
    "sources": [
      {
        "id": "file_source789",
        "object": "source",
        "kind": "video",
        "format": "mp4",
        "type": "video/mp4",
        "filesize": 9876543,
        "original": true,
        "src": "https://my-project.ittybit.net/examples/movies/escapes.mp4",
        "filename": "escapes.mp4",
        "created": "2023-02-02T14:30:00Z",
        "updated": "2023-02-02T14:30:00Z"
      }
    ],
    "original": "https://my-project.ittybit.net/examples/movies/escapes.mp4",
    "status": "ready",
    "created": "2023-02-02T14:30:00Z",
    "updated": "2023-02-02T14:30:00Z"
  },
  "links": {
    "self": "/media/med_newlyCreated"
  }
}

Get media by ID

Retrieves a specific media item by its ID

GET
/media/{id}

Authorization

AuthorizationRequiredBearer <token>

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

In: header

Path Parameters

idRequiredstring

The media ID

Response Body

Media item details

TypeScript Definitions

Use the response body type in TypeScript.

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

Demonstrates a successful response when retrieving a video media item with associated source files and metadata

{
  "meta": {
    "id": "req_abc123def456",
    "method": "GET",
    "url": "/media/med_53mexc77hDAqESQ9",
    "version": "2024-03-21",
    "status": 200,
    "org_id": "org_01J9QT9Q853B3P8PV33G8FR0YZ",
    "project_id": "prj_43b8xt37gTWV",
    "object": "media",
    "created": "2025-04-25T12:00:00.000Z"
  },
  "data": {
    "id": "med_53mexc77hDAqESQ9",
    "object": "media",
    "org_id": "org_01J9QT9Q853B3P8PV33G8FR0YZ",
    "project_id": "prj_43b8xt37gTWV",
    "live_mode": true,
    "kind": "video",
    "type": "video/mp4; codecs='avc1.6431, mp4a.40.2'",
    "width": 1280,
    "height": 720,
    "duration": 653.791667,
    "filesize": 169612362,
    "sources": [
      {
        "id": "file_53mexc77Rzty11fP",
        "object": "source",
        "kind": "video",
        "format": "mp4",
        "type": "video/mp4; codecs='avc1.6431, mp4a.40.2'",
        "filesize": 169612362,
        "original": true,
        "src": "https://example.com/videos/sample.mp4",
        "filename": "sample.mp4",
        "created": "2023-04-23T14:34:08.411Z",
        "updated": "2023-04-23T14:34:08.411Z"
      }
    ],
    "status": "ready",
    "created": "2023-04-23T14:34:08.311Z",
    "updated": "2023-04-23T14:34:08.311Z",
    "original": "https://example.com/videos/sample.mp4"
  },
  "links": {
    "self": "https://api.ittybit.com/media/med_53mexc77hDAqESQ9"
  }
}

Delete media by ID

Deletes a specific media item by its ID

DELETE
/media/{id}

Authorization

AuthorizationRequiredBearer <token>

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

In: header

Path Parameters

idRequiredstring

The media ID

Response Body

Media deleted successfully

TypeScript Definitions

Use the response body type in TypeScript.

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

{
  "meta": {
    "id": "req_pqr456stu789",
    "method": "DELETE",
    "url": "/media/med_53mexc77hDAqESQ9",
    "version": "2024-03-21",
    "status": 200,
    "org_id": "org_01J9QT9Q853B3P8PV33G8FR0YZ",
    "project_id": "prj_43b8xt37gTWV",
    "object": "confirmation",
    "created": "2025-04-25T12:05:00.000Z"
  },
  "data": {
    "message": "Media med_53mexc77hDAqESQ9 deleted successfully."
  },
  "links": {
    "self": "https://api.ittybit.com/media/med_53mexc77hDAqESQ9"
  }
}

Delete a FileDELETE

Previous Page

List MediaGET

Next Page