Introduction
The ittybit API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-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 the media in your account.
All requests use a base URL of https://api.ittybit.com
.
The one exception is adding new media, which uses https://uploads.ittybit.com
Read more: Ittybit API Quick Start Tutorial
Authentication
The Ittybit API uses API Keys to authenticate requests. You can view and manage your account's keys in the Ittybit Admin.
You may add different keys to separate operations for your development and production environments.
Your API Keys give privileged access to your account resources so they should be kept secret. Be careful not to share them in publicly accessible areas such as GitHub, client-side code, etc.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication, or with an invalid API Key, 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 versions may be deprecated in future, although in those cases we will provide at least 6 months notice and work with you to upgrade to a more recent API version smoothly.
Responses
The Ittybit API returns JSON encoded responses.
Each successful response includes a meta
prop containing information about the request and response, a data
prop containing the resource, and a links
prop containing endpoints you can use to access additional resources.
Responses with an error will contain a meta
prop and an error
prop.
Media
Media is the core resource in the Ittybit API.
Media can have a kind
of video
, image
, or audio
. More kinds may be added in future.
To create a Media resource, you POST
to the uploads endpoint at https://uploads.ittybit.com/media
All other endponts use https://api.ittybit.com
and allow you to retrieve and update individual Media resources, as well as list all Media items.
Media are identified by a globally unique random ID.
List Media
Gets a list of all the Media available in your Ittybit account.
Accepts query parameters which allow you to filter results.
Responses include pagination information which you can use to fetch the next batch.
limit
The maximum number of results to return. Default is 10.
integer(min:1,max:250)
orderBy
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 account.
You can upload a file directly or we can ingest a file from either any publicly-accessible URL or 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.
There is also a soft filesize limit on each account. Please contact us if you run in to Request Entity Too Large
errors.
Note – This endpoint uses https://uploads.ittybit.com
and requests should be sent as multipart/form-data
.
(Technical reason for the nerds like us who are curious – it allows us to process many large files in parallel without degrading API performance)
file
Attachment e.g. from a form `input` with `type="file"`
file
url
A publicly accessible URL to a media file
string
Request Body Parameters
Get Media
Get a single Media resource, including URLs for preview, poster, and playback (automagically selecting best option for your viewer's device and connection speed).
Responses contain the full object, along with a sources
array containing all the playable sources derived from this Media resource.
id Required
The ID of the Media resource you want to retrieve
string
URL 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 deplying 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 your List of Media. The GET /media/:id
resource endpoint will remain accessible and historical usage data will be retained.
id Required
The ID of the Media resource you want to retrieve
string
URL Parameters
Videos
Media can be of the kind Video, and it is helpful for some products to deal with Video resources directly. The Video endpoints allow exactly that.
To upload video, you can post to the Video endpoints. You can also list all Media with the kind video.
Videos are identified by a globally unique random ID.
List Videos
Gets a list of all the Videos available in your Ittybit account.
Accepts query parameters which allow you to filter results.
Responses include pagination information which you can use to fetch the next batch.
limit
The maximum number of results to return. Default is 10.
integer(min:1,max:250)
orderBy
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
Images
Media can be of the kind Image, and it is helpful for some products to deal with Image resources directly. The Image endpoints allow exactly that.
To upload an image, you can post to the Images endpoints. You can also list all Media with the kind images.
Images are identified by a globally unique random ID.
List Images
Gets a list of all the Images available in your Ittybit account.
Accepts query parameters which allow you to filter results.
Responses include pagination information which you can use to fetch the next batch.
limit
The maximum number of results to return. Default is 10.
integer(min:1,max:250)
orderBy
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
Audio
Coming Soon – if you would like to join our closed beta for Audio Uploads please Contact Us
Media can be of the kind Audio, and it is helpful for some products to deal with Audio resources directly. The Audio endpoints allow exactly that.
To upload audio, you can post to the Audio endpoints. You can also list all Media with the kind audio.
Audio are identified by a globally unique random ID.
List Audio
Gets a list of all the Audio resources available in your Ittybit account.
Accepts query parameters which allow you to filter results.
Responses include pagination information which you can use to fetch the next batch.
limit
The maximum number of results to return. Default is 10.
integer(min:1,max:250)
orderBy
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")