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.

    Query Parameters

  • 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")

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)

    Request Body Parameters

  • file

    Attachment e.g. from a form `input` with `type="file"`

    file

  • url

    A publicly accessible URL to a media file

    string

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.

    URL Parameters

  • id Required

    The ID of the Media resource you want to retrieve

    string

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.

    URL Parameters

  • id Required

    The ID of the Media resource you want to retrieve

    string

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.

    Query Parameters

  • 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")

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.

    Query Parameters

  • 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")

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.

    Query Parameters

  • 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")