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 Tasks, Workflows, and Analytics Data.
All requests use a base URL of https://api.ittybit.com.
Requests
The Ittybit API uses standard HTTP verbs to perform actions on resources.
GET requests are used to retrieve resources from the API, POST requests are used to create new resources, and DELETE requests are used to remove resources.
We also use PUT and PATCH for updating resources: PUT is used to replace an existing resource, and PATCH is used to perform partial updates to a resource.
POST, PUT, and PATCH endpoints accept JSON-encoded request bodies1.
To avoid issues with double-encoding, we recommend setting the Content-Type header to application/json in your requests.
To avoid issues with character encoding, please ensure that your requests are made with UTF-8 encoding.
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.
Requests have a unique id and a status prop indicating the HTTP status code of the response. If you need to contact support about an issue, including a request_id is super helpful.
Success responses will typically return either an object or a list of objects, depending on the endpoint.
For list responses that are empty, the data prop will be an empty array.
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 resources2, for example the next page in a list of results, or the parent resource of an object.
Pagination
Some endpoints return a list of resources. In these cases, the response will include a meta prop with pagination information, and a data prop containing an array of resources, and a links prop containing endpoints you can use to access additional resources.
The meta prop will include a total prop indicating the total number of resources available, a limit prop indicating the maximum number of resources returned per page, a page prop indicating the current page, and a pages prop indicating the total number of pages available.
The links prop will include a self prop indicating the current page, a next prop indicating the next page, and a prev prop indicating the previous page. If there is no next or previous page, the value will be null.
Authentication
The Ittybit API uses API Keys to authenticate requests. You can view and manage your keys in the Ittybit Webapp.
You should pass your API Key in the Authorization header of your requests. The value should be prefixed with Bearer followed by a space and then your key e.g. Bearer sk_test_abcdefg....
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 an Accept-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.
Status Codes
The Ittybit API uses standard HTTP response codes to indicate the success or failure of an API request.
In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted, a request was not authorised, etc), and codes in the 5xx range indicate there is an error with Ittybit's service.
Note We use 200 OK for successful responses, even where 201 Created or 204 No Content might be more descriptive. This is because some clients (incorrectly) treat any status code other than 200 as an error, and we want to avoid this confusion.
Errors
If the Ittybit API encounters an error, it will return an error response with an appropriate HTTP status code and a JSON-encoded error object.
The error object will contain a meta prop with information about the request and response, and an error prop containing information about the error and a human-readable message explaining the issue.
If there is a problem with your request, the API will return a 4xx status code. If there is a problem with our servers, the API will return a 5xx status code.
If you are receiving a 5xx error, please contact support with the error message and any other relevant information. We'll work with you to solve the problem asap.
Rate Limits
The Ittybit API has rate limits in place to ensure fair usage and to protect the service from abuse.
If you exceed the rate limits, you will receive a 429 Too Many Requests response. The response will include a Retry-After header indicating how many seconds you should wait before making another request.
If you are concerned that you might exceed the rate limits, please contact support to discuss your requirements and we will be happy to set-up custom limits for your project.
Idempotency
We deduplicate API requests based on the Idempotency-Key header.
If you include this header in your request, we will ensure that the request is only processed once, even if it is made multiple times.
This is useful for requests that may be retried by your system, for example if your system crashes before it can process the response from the API.
Sending different request bodies with the same Idempotency-Key will result in an error.
Idempotency keys are valid for 24 hours from first creation. After this time, the key will expire and the request will no longer be deduplicated.
Note The Idempotency-Key header is supported for POST, PUT, and PATCH requests. GET and DELETE requests are idempotent by definition.
Live Mode
Ittybit can be used in Test Mode or Live Mode.
Test Mode is designed for development and testing. It allows you to test your integration with the Ittybit API without incurring charges. However media uploaded in Test Mode will be deleted after 24 hours, is limited to 20 seconds duration, and has an ittybit watermark.
Live Mode is designed for production. It allows you to use the Ittybit API to manage your media and other resources in a live environment.
Whether your request is in Test Mode or Live Mode is dictated by the API Key used in the Authorization header, and the mode can be found in the meta prop of the response.
Footnotes
-
We also accept form-encoded request bodies, but we recommend using JSON. Read more: API Design ↩
-
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. ↩