API Documentation

Introduction

The ittybit API is organized around RESTful principles. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies*, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the API to create, retrieve, update, and delete Media, as well as manage other resources such as Transforms, Workflows, and Analytics Data.

All requests use a base URL of https://api.ittybit.com.

Authentication

The Ittybit API uses API Keys to authenticate requests. You can view and manage your keys in the Ittybit Webapp.

Your API Keys give privileged access to your project resources so they should be kept secret. Be careful not to share them in publicly accessible areas such as GitHub, client-side code, etc.

It is recommended to setup separate projects (within a single Organisation) for each of your development and production environments, and to create different API Keys for each environment. This will allow you to separate your test and production media.

API requests without authentication, or with an invalid API Key, will fail. API requests must be made over HTTPS. Calls made over plain HTTP will also fail.

Versioning

The Ittybit API uses date based versioning. A new version is released whenever a backwards-incompatible change is made to the API.

You can ensure your operations use a specific API version by including a Ittybit-Version header in your requests. Requests with no version specified will use the most recent stable version available.

Available API versions and a list of all updates can be found in our Changelog.

Older API versions may be deprecated in future, although in those cases we will provide at least 3 months notice and work with you to upgrade to a more recent API version smoothly.

In the very rare case that a more urgent update is required – for example, to fix a security vulnerability – we will always contact your account admin directly.

Responses

The Ittybit API returns JSON encoded responses.

Each successful response includes a meta prop containing information about the request and response, and a data prop containing the resource.

Error responses will contain a meta prop, and an error prop containing information about the error and a human-readable message explaining the issue.

Both success and error responses may also include a links prop containing endpoints you can use to access additional resources, for example the next page in a list of results, or the parent resource of an object.

We have consciously chosen not to include a complete hypermedia implementation. The limited extra functionality is not worth increased response size for every request. Take away our RESTful badge if you want, we don't care.

Projects

Further API documentation is coming soon.

List Projects

Gets a list of all the Projects in your organisation.

Parameters

This endpoint has no parameters

Create Project

Create a new Project.

Parameters

This endpoint has no parameters

Get Project

Return a single Project object.

URL Parameters

id Required
The ID of the Project to retrieve.
string

Update Project

Updates a Project object.

URL Parameters

id Required
The ID of the Project to update.
string

Delete Project

Permanently deletes a Project object.

URL Parameters

id Required
The ID of the Project to delete.
string

Media

Media is the core resource in the Ittybit API.

Each file uploaded or ingested will create a new media item, and media items can have one or more Sources.

Media can have a kind of video, image, or audio depending on the mime (filetype) of the original file. More kinds may be added in future.

API endpoints starting with https://api.ittybit.com/media allow you to retrieve and update individual Media resources, as well as list all of your project's Media items.

Media are identified by a globally unique random ID.

List Media

Gets a list of all the Media available in your Ittybit project.

Accepts query parameters which allow you to filter, sort, order, and limit results.

Responses include pagination information which you can use to fetch the next batch.

Query Parameters

kind
Filter results by kind, only returning results that match the specified kind.
string("image"|"video"|"audio")
limit
The maximum number of results to return. Default is 10.
integer(min: 1,max: 250)
sort
Describes how to sort the results. Valid values are created, updated, or filesize. Default order is by time created.
string("created"|"updated"|"filesize")
order
Describes whether to sort results in ascending or descending order. Default is 'desc'.
string("asc"|"desc")

Example Response

{
  "meta": {
    "status": 200,
    "url": "/media",
    "method": "GET",
    "version": "2022-03-30"
  },
  "data": {
    "object": "list",
    "org_id": "org_zkmh6yn600se",
    "project_id": "prj_zkmh6yn600se",
    "live_mode": true,
    "items": [
      {
        "id": "med_zkmh6yn600se",
        "kind": "video",
        "sources": [
          "..."
        ],
        "metadata": {},
        "url": "https://my-app-name.ittybitcdn.com/med_zkmh6yn600se",
        "endpoint": "https://api.ittybit.com/media/med_zkmh6yn600se",
        "created": "2022-03-08T09:12:26.636Z",
        "updated": "2022-03-08T09:14:21.330Z"
      },
      "{...}"
    ],
    "limit": 10,
    "total": 435,
    "pages": 44,
    "page": 1,
    "has_more": true
  },
  "links": {
    "self": "https://api.ittybit.com/media",
    "next": "https://api.ittybit.com/media?page=2",
    "prev": null
  }
}

Create Media

Add a new Media resource to your Ittybit project.

You can ingest a file directly from either any publicly-accessible URL or provide a signed-URL for a resource in one of your cloud storage buckets.

Currently accepted video formats are MP4, MOV, MKV, HEVC, and WEBM whilst accepted image formats are JPEG, PNG, GIF, HEIC, and WEBP.

To create media by uploading a file – either from your server or directly from the client – look at Uploads.

Request Body Parameters

url Required
A publicly accessible URL to a media file
string

POST /media

curl -X POST "https://api.ittybit.com/media" \ 
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Ittybit-Version: 2022-03-30" \
-H "Content-Type: application/json" \
-d '{"url": "https://rickastley.com/video.mp4"}'

Example Response

{
  "meta": {
    "status": 200,
    "url": "/media",
    "method": "POST",
    "version": "2022-03-30"
  },
  "data": {
    "id": "med_zkmh6yn600se",
    "object": "media",
    "org_id": "org_n3rxy6l0o9c1",
    "project_id": "prj_n3rxy6l0o9c1",
    "live_mode": true,
    "kind": "video",
    "sources": [
      {
        "id": "src_zkmh6yn600se",
        "ref": "original",
        "kind": "video",
        "meta": {
          "format": "mp4",
          "mime": "video/mp4",
          "extension": "mp4",
          "filesize": 110842,
          "original_filesize": 110842,
          "width": 1920,
          "height": 1080,
          "orientation": "landscape",
          "duration": 185.24
        },
        "status": "ready",
        "url": "https://my-app-name.ittybitcdn.com/med_zkmh6yn600se/original.mp4",
        "endpoint": "https://api.ittybit.com/sources/src_zkmh6yn600se"
      }
    ],
    "url": "https://my-app-name.ittybitcdn.com/med_zkmh6yn600se",
    "endpoint": "https://api.ittybit.com/media/med_zkmh6yn600se",
    "updated": "2023-11-10T08:01:24.198Z",
    "created": "2023-11-10T08:01:24.198Z"
  },
  "links": {
    "self": "https://api.ittybit.com/media"
  }
}

Get Media

Return a single Media object, including any Sources associated with that Media.

URL Parameters

id Required
The ID of the Media resource you want to retrieve
string

Example Response

{
  "meta": {
    "status": 200,
    "url": "/media/med_zkmh6yn600se",
    "method": "GET",
    "version": "2022-03-30"
  },
  "data": {
    "id": "med_zkmh6yn600se",
    "object": "media",
    "org_id": "org_n3rxy6l0o9c1",
    "project_id": "prj_n3rxy6l0o9c1",
    "live_mode": true,
    "kind": "video",
    "sources": [
      {
        "id": "src_zkmh6yn600se",
        "ref": "original",
        "kind": "video",
        "meta": {
          "format": "mp4",
          "mime": "video/mp4",
          "width": 1920,
          "height": 1080,
          "orientation": "landscape",
          "filesize": 82157802,
          "duration": 212.04,
          "bitrate": 3099709,
          "frames": 5301,
          "fps": 25,
          "codecs": {
            "video": "h264",
            "bitdepth": 8,
            "color": "yuv420p",
            "range": "tv",
            "audio": "aac",
            "channels": 2,
            "sample": 44100
          }
        },
        "url": "https://my-app-name.ittybitcdn.com/src_zkmh6yn600se.mp4",
        "endpoint": "https://api.ittybit.com/sources/src_zkmh6yn600se",
        "status": "ready"
      },
      {
        "id": "src_zkmh6yn600sf",
        "ref": "poster",
        "kind": "image",
        "meta": {
          "format": "jpeg",
          "mime": "image/jpeg",
          "width": 1920,
          "height": 1080,
          "orientation": "landscape",
          "filesize": 78773,
          "frames": 1,
          "codecs": {
            "image": "jpeg",
            "bitdepth": 8,
            "color": "yuv420p",
            "range": "tv"
          }
        },
        "url": "https://my-app-name.ittybitcdn.com/src_zkmh6yn600sf.jpeg",
        "endpoint": "https://api.ittybit.com/sources/src_zkmh6yn600sf",
        "status": "ready"
      },
      {
        "id": "src_zkmh6yn600sg",
        "ref": "adaptive",
        "kind": "video",
        "meta": {
          "format": "hls",
          "mime": "application/x-mpegURL",
          "width": 1920,
          "height": 1080,
          "orientation": "landscape",
          "duration": 212.04,
          "frames": 5301,
          "variants": [
            {
              "width": 1920,
              "height": 1080,
              "fps": 25,
              "bitrate": 3099709
            },
            {
              "width": 1280,
              "height": 720,
              "fps": 25,
              "bitrate": 1536000
            },
            {
              "width": 960,
              "height": 540,
              "fps": 25,
              "bitrate": 1024000
            },
            {
              "width": 640,
              "height": 360,
              "fps": 25,
              "bitrate": 512000
            },
            {
              "width": 480,
              "height": 270,
              "fps": 25,
              "bitrate": 256000
            }
          ]
        },
        "url": "https://my-app-name.ittybitcdn.com/src_zkmh6yn600sg.m3u8",
        "endpoint": "https://api.ittybit.com/sources/src_zkmh6yn600sg",
        "status": "ready"
      }
    ],
    "metadata": {},
    "created": "2022-03-08T09:12:26.636Z",
    "updated": "2022-03-08T09:14:21.330Z",
    "status": "ready",
    "url": "https://my-app-name.ittybitcdn.com/med_zkmh6yn600se",
    "endpoint": "https://api.ittybit.com/media/med_zkmh6yn600se"
  },
  "links": {
    "parent": "https://api.ittybit.com/media",
    "self": "https://api.ittybit.com/media/med_zkmh6yn600se"
  }
}

Update Media

Update a Media resource, including its metadata and expiry time.

URL Parameters

id Required
The ID of the Media resource you want to update
string

Request Body Parameters

metadata
The metadata you want to update, as a valid JSON object. Note values are merged with existing metadata, with any new values added and existing values overwritten. To remove a value, set it to null.
object(max: 1024 bytes)
expires
The ISO 8601 date and time you want the media to expire. Invalid dates and dates in the past will be rejected. If expires is passed as null, the expires time will be removed from the media.
string e.g. "2023-11-10T08:06:24.198Z"(min: currentTime + 60 seconds,max: currentTime + 365 days)
timeout
The number of seconds from now that the media should expire. Only one of expires and timeout should be included in a request. If timeout is passed as null, the expires time will be removed from the media.
integer(min: 60,max: 31536000)

Example Response

{
  "meta": {
    "status": 200,
    "url": "/media/med_zkmh6yn600se",
    "method": "PUT",
    "version": "2022-03-30"
  },
  "data": {
    "id": "med_zkmh6yn600se",
    "object": "media",
    "org_id": "org_n3rxy6l0o9c1",
    "project_id": "prj_n3rxy6l0o9c1",
    "live_mode": true,
    "kind": "video",
    "sources": [
      "..."
    ],
    "metadata": {
      "user_id": 123
    },
    "created": "2022-03-08T09:12:26.636Z",
    "updated": "2023-11-10T08:01:24.198Z",
    "status": "ready",
    "url": "https://my-app-name.ittybitcdn.com/med_zkmh6yn600se",
    "endpoint": "https://api.ittybit.com/media/med_zkmh6yn600se"
  },
  "links": {
    "parent": "https://api.ittybit.com/media",
    "self": "https://api.ittybit.com/media/med_zkmh6yn600se"
  }
}

Delete Media

Permanently removes a Media resource and all its Sources from your account.

This operation is non-reversible so please test accordingly before deploying to production environments. Once a Media resource is deleted we will remove all the files associated with it, and playback links will no longer work. You will no longer be billed for storage or delivery.

Deleted media will no longer show in the GET /media list.

The GET /media/:id endpoint will remain accessible, returning the object with no sources and deleted status. Historical analytics data will also be retained.

If you would like us to permanently delete all of the data associated with a Media resource, please contact us.

URL Parameters

id Required
The ID of the Media resource you want to retrieve
string

Example Response

{
  "meta": {
    "status": 200,
    "url": "/media/med_zkmh6yn600se",
    "method": "DELETE",
    "version": "2022-03-30"
  },
  "data": {
    "id": "med_zkmh6yn600se",
    "object": "media",
    "org_id": "org_n6y0zjy600se",
    "project_id": "prj_6y0zjy600se",
    "live_mode": true,
    "sources": [],
    "status": "deleted",
    "created": "2022-03-08T09:12:26.636Z",
    "updated": "2023-11-10T08:01:24.198Z"
  },
  "links": {
    "parent": "https://api.ittybit.com/media",
    "self": "https://api.ittybit.com/media/med_zkmh6yn600se"
  }
}

Sources

Sources are objects representing the different versions of a Media item.

All Media items start with one Source, which is the original file uploaded to Ittybit, and may have additional Sources created by Transforms or Workflows.

For example, a Media with the original kind of video may have sources created for a JPEG thumbnail and for an adaptive streaming format, or a Media with original kind of image that has been transformed to modern formats may have sources for webp and avif versions.

Media object responses include an array of all available sources, however many developers find it easier to store only the ID or URL of a specific source in their own database. These endpoints enable a more efficient way to fetch, update, and delete individual sources.

List Sources

Gets a list of all the Sources in your project.

Parameters

This endpoint has no parameters

Get Source

Return a single Source object.

URL Parameters

id Required
The ID of the Source to retrieve.
string

Update Source

Updates a Source object.

URL Parameters

id Required
The ID of the Source to update.
string

Delete Source

Permanently deletes a Source object.

URL Parameters

id Required
The ID of the Source to delete.
string

Uploads

To securely upload media to Ittybit, you can use the Uploads API.

Because uploads typically happen from a client-side application, and you do not want to expose your API key to the public, you must first generate an upload URL to POST your media file to.

Upload URLs are short-lived and one-time use URLs which are authenticated to upload directly to your project. You can use uploads URLs in form requests from your client to upload media directly to Ittybit, or you can use them in your server-side code to upload media from your server.

For ingesting media from publicly accessible URLs, or adding media in bulk, see the Media endpoints.

Create Upload URL

Creates a short-lived upload URL which is safe to use on the client side of your application.

Accepts body parameters for adding metadata to the uploaded media, or for adjusting the upload settings.

Request Body Parameters

timeout
The number of seconds before the upload URL expires. Default is 300 seconds.
integer(min: 10,max: 3600)
workflow_id
The ID of the Workflow to use for processing the uploaded media. If not specified, your project's default workflow will be used.
string
metadata
Add custom metadata to the uploaded media. This metadata will be returned in the response when you list your media. Useful for attaching e.g. your end-user's ID to the media.
object
expires
The number of seconds before the uploaded media is automatically deleted. Default is null.
integer(min: 60,max: 31536000)

Example Response

{
  "meta": {
    "status": 200,
    "url": "/uploads",
    "method": "POST",
    "version": "2022-03-30"
  },
  "data": {
    "id": "upl_zkmh6yn600se",
    "object": "upload",
    "org_id": "org_zkmh6yn600se",
    "project_id": "prj_zkmh6yn600se",
    "media_id": "med_zkmh6yn600se",
    "workflow_id": null,
    "live_mode": true,
    "metadata": {},
    "expires": null,
    "url": "https://uploads.ittybit.com/signed?key=...",
    "created": "2023-11-10T08:01:24.198Z",
    "timeout": "2023-11-10T08:06:24.198Z"
  },
  "links": {
    "self": "https://api.ittybit.com/uploads"
  }
}

Transforms

Further API documentation is coming soon.

List Transforms

Gets a list of all the Transforms in your project.

Parameters

This endpoint has no parameters

Create Transform

Create a new Transform task. If valid, the Transform will add a new Source to the associated Media object.

Parameters

This endpoint has no parameters

Get Transform

Return a single Transform object.

URL Parameters

id Required
The ID of the Transform to retrieve.
string

Delete Transform

Permanently deletes a Transform object.

URL Parameters

id Required
The ID of the Transform to delete.
string

Intelligence

Further API documentation is coming soon.

List Intelligence Tasks

Gets a list of all the Intelligence Tasks in your project.

Parameters

This endpoint has no parameters

Create Intelligence Task

Create a new Intelligence Task. If valid, will add a new intelligence prop to the associated Media object.

Parameters

This endpoint has no parameters

Get Intelligence Task

Return a single Intelligence Task.

URL Parameters

id Required
The ID of the Intelligence Task to retrieve.
string

Workflows

Further API documentation is coming soon.

List Workflows

Gets a list of all the Workflows in your project.

Parameters

This endpoint has no parameters

Create Workflow

Create a new Workflow.

Parameters

This endpoint has no parameters

Get Workflow

Return a single Workflow object.

URL Parameters

id Required
The ID of the Workflow to retrieve.
string

Update Workflow

Updates a Workflow object.

URL Parameters

id Required
The ID of the Workflow to update.
string

Delete Workflow

Permanently deletes a Workflow object.

URL Parameters

id Required
The ID of the Workflow to delete.
string

Webhooks

Further API documentation is coming soon.

List Webhooks

Gets a list of all the Webhooks in your project.

Parameters

This endpoint has no parameters

Create Webhook

Create a new Webhook.

Parameters

This endpoint has no parameters

Get Webhook

Return a single Webhook object.

URL Parameters

id Required
The ID of the Webhook to retrieve.
string

Update Webhook

Updates a Webhook object.

URL Parameters

id Required
The ID of the Webhook to update.
string

Delete Webhook

Permanently deletes a Webhook object.

URL Parameters

id Required
The ID of the Webhook to delete.
string

Analytics

Further API documentation is coming soon.

Get Stats

Returns project level stats

Parameters

This endpoint has no parameters

Get Media Stats

Returns stats for a specific Media object.

Parameters

This endpoint has no parameters

Get Project Stats

Returns stats for a specific Project.

Parameters

This endpoint has no parameters

Domains

Further API documentation is coming soon.

List Domains

Gets a list of all the custom video domains in your project.

Parameters

This endpoint has no parameters

Create Domain

Create a new Domain.

Parameters

This endpoint has no parameters

Get Domain

Return a single Domain object.

URL Parameters

id Required
The ID of the Domain to retrieve.
string

Delete Domain

Permanently deletes a Domain object.

URL Parameters

id Required
The ID of the Domain to delete.
string

API Documentation

List Projects

Parameters

Create Project

Parameters

Get Project

URL Parameters

id Required

Update Project

URL Parameters

id Required

Delete Project

URL Parameters

id Required

List Media

Query Parameters

kind

limit

sort

order

Create Media

Request Body Parameters

url Required

Get Media

URL Parameters

id Required

Update Media

URL Parameters

id Required

Request Body Parameters

metadata

expires

timeout

Delete Media

URL Parameters

id Required

List Sources

Parameters

Get Source

URL Parameters

id Required

Update Source

URL Parameters

id Required

Delete Source

URL Parameters

id Required

Create Upload URL

Request Body Parameters

timeout

workflow_id

metadata

expires

List Transforms

Parameters

Create Transform

Parameters

Get Transform

URL Parameters

id Required

Delete Transform

URL Parameters

id Required

List Intelligence Tasks

Parameters

Create Intelligence Task

Parameters

Get Intelligence Task

URL Parameters

id Required

List Workflows

Parameters

Create Workflow

Parameters

Get Workflow

URL Parameters

id Required

Update Workflow

URL Parameters

id Required