Media

Media Items

# Media
POST https://api.ittybit.com/media
GET https://api.ittybit.com/media
# Media Item
GET https://api.ittybit.com/media/:id
PATCH https://api.ittybit.com/media/:id
DELETE https://api.ittybit.com/media/:id

Media Items act as containers for your related media assets.

The simplest Media Item could contain just a single image. Whilst more complex examples might include multiple audio and video tracks, as well as multiple intelligence items and custom metadata.

Each new upload or ingested file creates a new Media Item.

Metadata

Media Items can also contain custom metadata in a JSON object containing your own key-value pairs.

Metadata is useful for storing additional information you need to associate with the media. Other customer use metadata to store things like:

User ID of the user who uploaded the media
Content ID of an article the media is associated with
Expiry Date for media that can be periodically cleaned up
Custom Tags for easy search and filtering

Endpoints

Create Media Item

const ITTYBIT_API_KEY = "YOUR API KEY HERE"
const URL = "YOUR FILE URL HERE"
const response = await fetch(`https://api.ittybit.com/media`, {
  headers: {
    Method: "POST",
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    body: JSON.stringify({
      url: ${URL},
      filename: "new-filename.mp4",
      folder: "your/folder/path",
      title: "My Video Upload",
      metadata: {
        original_filename: "your-file.mp4",
        user_id: "123",
        source: "YourApp/iOS",
        purpose: "profile_video",
      },
    }),
  },
});

curl -X POST "https://api.ittybit.com/media"
-H "Authorization: Bearer ITTYBIT_API_KEY"
-H "Content-Type: application/json"
-d '{
  "url": "https://yourbucket.s3.amazonaws.com/your-file.mp4?signature=1234567890&expires=1234567890",
  "filename": "new-filename.mp4",
  "folder": "your/folder/path",
  "title": "My Video Upload",
  "metadata": {
    "original_filename": "your-file.mp4",
    "user_id": "123",
    "source": "YourApp/iOS",
    "purpose": "profile_video"
  }
}'

Endpoint

https://api.ittybit.com/media

HTTP Method

POST

Description

Creates a new media item by ingesting a file from a url.

Note: To view a complete list of the available ways of uploading or ingesting media, see the Uploads API documentation.

{
  "meta":{
    "id": "req_abcdefgh1234",
    "method": "POST",
    "host": "https://api.ittybit.com",
    "path": "/media",
    "version": "2024-08-21",
    "status": 200,
    "org_id": "org_abcdefgh1234",
    "project_id": "prj_abcdefgh5678",
    "type": "object"
  },
  "data": {
    "id": "med_abcdefgh5678",
    "object": "media",
    "title": "My Video Upload",
    "folder": "your/folder/path",
    "kind": "video",
    "width": 1920,
    "height": 1080,
    "duration": 60.0,
    "fps": 30.0,
    "filesize": 12345678,
    "total_filesize": 12345678,
    "sources": [
      // ... Source object
      // https://ittybit.com/docs/sources
    ],
    "tracks": [],
    "intelligence": [],
    "original": "https://prj_abcdefgh1234.ittybitcdn.com/your/folder/path/new-filename.mp4",
    "placeholder": "data:image/png;base64,aHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g/dj1kUXc0dzlXZ1hjUSZwcD15Z1VJY21samEzSnZiR3clM0Q=",
    "background": "#FF94A4",
    "metadata": {
      "original_filename": "your-file.mp4",
      "user_id": "123",
      "source": "YourApp/iOS",
      "purpose": "profile_video"
    },
    "status": "active",
    "created": "2024-08-30T15:00:00Z",
    "updated": "2024-08-30T15:00:01Z",
  },
  "links": {
    "self": "https://api.ittybit.com/media/med_abcdefgh5678",
    "parent": "https://api.ittybit.com/media",
  }
}

Body Parameters

url string (required)

A URL to the file to ingest. The file must be publicly accessible or have a signed URL with an expiry > 10 minutes in the future.
title string

A title for the media item. This can be used to identify the media item in the media library. Defaults to the filename.
filename string

The filename will be used in the URL that accesses the original source for the media. It can contain letters, numbers, underscores, and hyphens. If not provided, we will use the file's id and an extension based on the filetype e.g. /[folder_path]/file_abcdefgh1234.mp4.

Note that the filename must be unique within the given folder unless the overwrite parameter is set to true.
folder string

An optional folder value can be provided to help you organise your media, or to match the folder structure of an existing media library. Folder values can be a path or a single folder name and will be used in the URLs used to access your media files. If not provided, we will use the default folder for your project e.g. /media/[filename].
overwrite boolean

If true, the media item will be created even if another file with the same filename already exists in the given folder. Note that overwritten files are not deleted and can be accessed (or renamed or deleted) via the Files API. Defaults to false.
metadata object

A set of key-value pairs to store with the media item. Values must be strings. In addition, nested objects are not supported – if you have an interesting use case for this, please let us know about it.

List Media Items

const response = await fetch(`https://api.ittybit.com/media`, {
  headers: {
    Authorization: `Bearer ${ITTYBIT_API_KEY}`,
  },
});

curl "https://api.ittybit.com/media"
-H "Authorization: Bearer ITTYBIT_API_KEY"

Endpoint

https://api.ittybit.com/media

HTTP Method

GET

Description

Returns a list of all media items in your project.

{
  "meta":{
    "id": "req_abcdefgh1234",
    "org_id": "org_abcdefgh1234",
    "project_id": "prj_abcdefgh1234",
    "method": "GET",
    "host": "https://api.ittybit.com",
    "path": "/media",
    "query": {
      "your_custom_key": "Your custom value",
    },
    "version": "2024-08-21",
    "status": 200,
    "type": "list",
    "total": 120,
    "limit": 12,
    "page": 1,
    "pages": 10
  },
  "data": [
    {
    "id": "med_abcdefgh1234",
    "object": "media",
    "kind": "video",
    "width": 1920,
    "height": 1080,
    "duration": 60,
    "fps": 30,
    "filesize": 12345678,
    "sources": [
      // ... Source objects
      // https://ittybit.com/docs/sources
    ],
    "tracks": [
      // ... Track objects
      // https://ittybit.com/docs/tracks
    ],
    "intelligence": [
      // ... Intelligence objects
      // https://ittybit.com/docs/intelligence
    ],
    "metadata": {
      "your_custom_key": "Your custom value",
      "fav_number": "69",
      "is_nice": "true"
    },
    "created": "2024-08-30T13:00:00Z",
    "updated": "2024-08-30T13:01:00Z",
    }
  ],
  "links": {
    "self": "https://api.ittybit.com/media",
    "next": "https://api.ittybit.com/media?page=2",
    "prev": null,
  }
}

Query Parameters

page integer

The page number to return. Default is 1.
limit integer

The number of items to return per page. Default is 12. Maximum is 100.
sort string

The field to sort by. Default is created. Possible values are created, updated, filesize, duration, width, height, fps, or filename.
order string

The order to sort by. Default is desc. Possible values are asc, desc.
kind string

The kind of media to return. Possible values are image, video, audio.
metadata.KEY string

Filter media by metadata values. Multiple parameters can be chained, and results will contain only the results that match all the provided metadata key-value pairs e.g. to find all media with a user_id of 123 and a source of YourApp/iOS, you can add the query params ?metadata.user_id=123&metadata.source=YourApp/iOS. Values are case-sensitive, will be URL-decoded for comparison, and must be an exact string match.

View Media Item

const response = await fetch(`https://api.ittybit.com/media/med_abcdefgh1234`, {
  headers: {
    Authorization: `Bearer ${ITTYBIT_API_KEY}`,
  },
});

curl "https://api.ittybit.com/media/med_abcdefgh1234"
-H "Authorization: Bearer ITTYBIT_API_KEY"

Endpoint

https://api.ittybit.com/media/:id

HTTP Method

GET

Description

Returns the details for a single media item.

{
  "meta":{
    "id": "req_abcdefgh1234",
    "org_id": "org_abcdefgh1234",
    "project_id": "prj_abcdefgh1234",
    "method": "GET",
    "host": "https://api.ittybit.com",
    "path": "/media/med_abcdefgh1234",
    "version": "2024-08-21",
    "status": 200,
    "type": "object"
  },
  "data": {
    "id": "med_abcdefgh1234",
    "object": "media",
    "title": "My Video Upload",
    "folder": "med_abcdefgh1234",
    "kind": "video",
    "width": 1920,
    "height": 1080,
    "duration": 60,
    "fps": 30,
    "filesize": 12345678,
    "total_filesize": 24681357,
    "sources": [
      // ... Source objects
      // https://ittybit.com/docs/sources
    ],
    "tracks": [
      // ... Track objects
      // https://ittybit.com/docs/tracks
    ],
    "intelligence": [
      // ... Intelligence objects
      // https://ittybit.com/docs/intelligence
    ],
    "original": "https://prj_abcdefgh1234.ittybitcdn.com/your/folder/path/new-filename.mp4",
    "poster": "https://prj_abcdefgh1234.ittybitcdn.com/your/folder/path/poster.jpg",
    "speech": "https://prj_abcdefgh1234.ittybitcdn.com/your/folder/path/speech.json",
    "subtitles": "https://prj_abcdefgh1234.ittybitcdn.com/your/folder/path/subtitles.srt",
    "placeholder": "data:image/png;base64,aHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g/dj1kUXc0dzlXZ1hjUSZwcD15Z1VJY21samEzSnZiR3clM0Q=",
    "background": "#FF94A4",
    "metadata": {
      "original_filename": "your-file.mp4",
      "user_id": "123",
      "source": "YourApp/iOS",
      "purpose": "profile_video"
    },
    "created": "2024-08-30T13:00:00Z",
    "updated": "2024-08-30T13:01:00Z",
  },
  "links": {
    "self": "https://api.ittybit.com/media/med_abcdefgh1234",
    "parent": "https://api.ittybit.com/media",
  }
}

Response Parameters

id string

Unique identifier for the media item.
object string

The type of object. Always media.
title string

The title of the media item or null if no title has been set.
folder string

The folder the media item is stored in or null if no folder has been set.
kind string

The kind of the original file. Possible values are image, video, audio.
width integer

The width of the original file in pixels.
height integer

The height of the original file in pixels.
duration number

The duration of the original file in seconds (for video, audio, and animated images).
fps number

The frames per second of the original file (for video and animated images).
filesize integer

The size of the original file in bytes.
total_filesize integer

The total size of all the media files in the media item. This is the sum of the filesizes of all source, track, and intelligence files.
sources array

An array of Source objects that describe the different variants of the media that have been created.
tracks array

An array of Track objects that describe additional metadata files that have been created for the media. This is only present for media with a kind of video or audio.
intelligence array

An array of Intelligence objects that describe the rich data that has been extracted from the media.
original string

The URL to the original asset.
... urls strings

If the media item has additional sources, tracks, or intelligence, and any of those files have a label, then the url to the file will be included in the top-level media object with the label as the key e.g. a source with the label poster will be included as poster: https://[... url to file].
placeholder string

A base64-encoded placeholder image for the media item. This is only present for media with a kind of image or video.
background string

The dominant color in the original asset, in hexadecimal format e.g. #FF94A4. This is only present for media with a kind of image or video.
metadata object

A JSON object containing key-value pairs forany custom metadata you have attached to the media item.
created datetime

The date and time the media item was created. ISO 8601 format.
updated datetime

The date and time the media item was last updated. ISO 8601 format.

Update Media Item

const ITTYBIT_API_KEY = "YOUR API KEY HERE"
const response = await fetch(`https://api.ittybit.com/media/med_abcdefgh1234`, {
  headers: {
    Method: "PATCH",
    Authorization: `Bearer ${ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
    body: JSON.stringify({
      title: "My New Title",
      folder: "new/folder/path",
      metadata: {
        "new_value": "New value",
        "purpose": null
      }
    }),
  },
});

curl -X PATCH "https://api.ittybit.com/media/med_abcdefgh1234"
-H "Authorization: Bearer ITTYBIT_API_KEY"
-H "Content-Type: application/json"
-d '{
  "title": "My New Title",
  "folder": "new/folder/path",
  "metadata": {
    "new_value": "New value",
    "purpose": null
  }
}'

Endpoint

https://api.ittybit.com/media/:id

HTTP Method

PATCH

Description

Update a media item's title, folder, and/or metadata.

{
  "meta":{
    "id": "req_abcdefgh1234",
    "org_id": "org_abcdefgh1234",
    "project_id": "prj_abcdefgh5678",
    "method": "PATCH",
    "host": "https://api.ittybit.com",
    "path": "/media",
    "version": "2024-08-21",
    "status": 200,
    "type": "object"
  },
  "data": {
    "id": "med_abcdefgh1234",
    "object": "media",
    "title": "My New Title",
    "folder": "new/folder/path",
    "kind": "video",
    "width": 1920,
    "height": 1080,
    "duration": 60,
    "fps": 30,
    "filesize": 12345678,
    "total_filesize": 24681357,
    "sources": [
      // ... Source object
      // https://ittybit.com/docs/sources
    ],
    "tracks": [
      // ... Track object
      // https://ittybit.com/docs/tracks
    ],
    "intelligence": [
      // ... Intelligence object
      // https://ittybit.com/docs/intelligence
    ],
    "metadata": {
      "original_filename": "your-file.mp4",
      "user_id": 123,
      "source": "YourApp/iOS",
      "new_value": "New value"
    },
    "status": "active",
    "created": "2024-08-30T13:00:00Z",
    "updated": "2024-08-30T14:00:00Z",
  },
  "links": {
    "self": "https://api.ittybit.com/media/med_abcdefgh1234",
    "parent": "https://api.ittybit.com/media",
  }
}

Body Parameters

title string

A new title for the media item.
folder string

A new folder for the media item. All Source, Intelligence, and Track files will be moved to the new folder. Note that existing links will need to be updated. Filenames can be updated by using the Files API.
overwrite boolean

If true, the folder will be updated even if files already exist in the given folder with the same filename as files in the media item. Note that overwritten files are not deleted and can be accessed (or renamed or deleted) via the Files API. Defaults to false.
metadata object

The new metadata to attach to the media item. Values will be merged with existing values. To remove a value you can set it to null. To remove all metadata, you can pass an empty object: {}.

Delete Media Item

const response = await fetch(`https://api.ittybit.com/media/med_abcdefgh1234`, {
  headers: {
    Method: "DELETE",
    Authorization: `Bearer ${ITTYBIT_API_KEY}`,
  },
});

curl -X DELETE "https://api.ittybit.com/media/med_abcdefgh"
-H "Authorization: Bearer ITTYBIT_API_KEY"

Endpoint

https://api.ittybit.com/media/:id

HTTP Method

DELETE

Description

Deletes a media item and all its sources, tracks, intelligence, and metadata.

Individual files can be deleted using the Files API.

NOTE: To avoid accidental data loss we retain the data and files for ~24 hours before permanently deleting it. If you need to restore an item within this period, please contact support.

{
  "meta":{
    "id": "req_abcdefgh1234",
    "org_id": "org_abcdefgh1234",
    "project_id": "prj_abcdefgh1234",
    "method": "DELETE",
    "host": "https://api.ittybit.com",
    "path": "/media/med_abcdefgh1234",
    "version": "2024-08-21",
    "status": 200,
    "type": null
  },
  "data": null,
  "links": {
    "parent": "https://api.ittybit.com/media",
  }
}