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.
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.
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")
Query Parameters
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.
url Required
A publicly accessible URL to a media file
string
Request Body Parameters
Get Media
Return a single Media object, including any Sources associated with that Media.
id Required
The ID of the Media resource you want to retrieve
string
URL Parameters
Update Media
Update a Media resource, including its metadata and expiry time.
id Required
The ID of the Media resource you want to update
string
URL 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-03-12T18:45:26.818Z"(min: currentTime + 60 seconds,max: currentTime + 365 days)
timeout
The number of seconds from now that the media should expire. Only one of
expiresandtimeoutshould be included in a request. If timeout is passed asnull, the expires time will be removed from the media.integer(min: 60,max: 31536000)
Request Body Parameters
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.
id Required
The ID of the Media resource you want to retrieve
string
URL Parameters
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.
Read more: Ittybit Guide to Uploading Media
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.
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)
Request Body Parameters
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.
id Required
The ID of the Source to retrieve.
string
URL Parameters
Update Source
Updates a Source object.
id Required
The ID of the Source to update.
string
URL Parameters
Delete Source
Permanently deletes a Source object.
id Required
The ID of the Source to delete.
string
URL Parameters
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.
id Required
The ID of the Intelligence Task to retrieve.
string
URL Parameters
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
Get Transform
Return a single Transform object.
id Required
The ID of the Transform to retrieve.
string
URL Parameters
Delete Transform
Permanently deletes a Transform object.
id Required
The ID of the Transform to delete.
string
URL Parameters
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.
id Required
The ID of the Workflow to retrieve.
string
URL Parameters
Update Workflow
Updates a Workflow object.
id Required
The ID of the Workflow to update.
string
URL Parameters
Delete Workflow
Permanently deletes a Workflow object.
id Required
The ID of the Workflow to delete.
string
URL Parameters
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.
id Required
The ID of the Webhook to retrieve.
string
URL Parameters
Update Webhook
Updates a Webhook object.
id Required
The ID of the Webhook to update.
string
URL Parameters
Delete Webhook
Permanently deletes a Webhook object.
id Required
The ID of the Webhook to delete.
string
URL Parameters
Players
Further API documentation is coming soon.
List Players
Gets a list of all the custom video players in your project.
Parameters
This endpoint has no parameters
Create Player
Create a new Player.
Parameters
This endpoint has no parameters
Get Player
Return a single Player object.
id Required
The ID of the Player to retrieve.
string
URL Parameters
Update Player
Updates a Player object.
id Required
The ID of the Player to update.
string
URL Parameters
Delete Player
Permanently deletes a Player object.
id Required
The ID of the Player to delete.
string
URL Parameters
Analytics
Further API documentation is coming soon.
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.
id Required
The ID of the Project to retrieve.
string
URL Parameters
Update Project
Updates a Project object.
id Required
The ID of the Project to update.
string
URL Parameters
Delete Project
Permanently deletes a Project object.
id Required
The ID of the Project to delete.
string