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, Automations, 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.
DELETE requests are used to remove resources.
We also use PUT and PATCH for updating resources:
PUT is used to wholly replace an existing resource.
PATCH is used to perform partial updates to a resource.
Request Bodies
POST, PUT, and PATCH endpoints accept JSON-encoded request bodies.
To avoid issues with double-encoding, we recommend setting the Content-Type header to application/json in your requests.
Character Encoding
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.
Request ID
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
Success responses will typically return either an object or a list of objects, depending on the endpoint. The meta.type prop will indicate whether the response is a list or an object.
For list responses that are empty, the data prop will be an empty array.
Error Responses
Error responses will contain a meta prop, and an error prop containing information about the error and a human-readable message explaining the issue.
Links
Both success and error responses may also include a links prop containing endpoints you can use to access additional resources1, 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 meta prop will include the additional props:
-
total integer
The total number of resources available
-
limit integer
The maximum number of resources returned per page
-
page integer
The current page
-
pages integer
The total number of pages available
The links prop will include:
-
self string
The URL to refetch the current page
-
next string
The URL to fetch the next page
-
prev string
The URL to fetch the previous page
If there is no next or previous page, the value for this prop will be null.
Authentication
The Ittybit API uses API Keys to authenticate requests.
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....
API requests without authentication, or with an invalid API Key, will fail.
Security
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.
You can view and manage your keys in the Ittybit Webapp.
Environments
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.
HTTPS
API requests must be made over HTTPS. Calls made over plain HTTP will also fail.
Versioning
The Ittybit API uses date based versioning.
We try to minimise breaking changes to the API, but will release a new version whenever a backwards-incompatible change is made.
Specifying a Version
To specify a version for your API request, include an Accept-Version header with the desired version date. For example: "Accept-Version": "2024-08-21".
Default Version
Requests with no version specified will always use the most recent stable version available.
Available Versions
Available API versions and a list of all updates can be found in our Changelog.
Deprecation Policy
Older API versions may be deprecated in future.
In those cases we will provide at least 3 months notice and work with you to upgrade to a more recent API version smoothly.
Security Vulnerabilities
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
2xxrange indicate success - codes in the
4xxrange indicate an error that failed given the information provided (e.g. a required parameter was omitted, a request was not authorised, etc) - codes in the
5xxrange 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.
The error respnse object will contain a meta prop with information about the request and response, including an appropriate HTTP status code.
It will also contain an error prop containing information about the error and a human-readable message explaining the issue.
4xx Errors
If there is a problem with your request, the API will return a 4xx status code.
The error prop will contain an id and a name for the error, and a message explaining the issue.
5xx Errors
If there is a problem with our servers, the API will return a 5xx status code.
Docs
The error prop may provide a docs prop which will provide a link to a page with more details about that kind of error.
Report issue
We may also provide a report prop which you can use to send an error report to our support team for further investigation.
Particularly if you are receiving 5xx errors, please do contact support. 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 POST requests based on the Idempotency-Key header 2.
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.
Valid Keys
The Idempotency-Key header must be a unique string between 16 and 32 characters in length.
A good option is to generate a hash from the values you are sending in the request.
Expiry
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.
Errors
Sending different request bodies with the same Idempotency-Key will result in an error.
Footnotes
-
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. ↩
-
GET,PUT, andDELETErequests are always idempotent by definition. Our particular implementation ofPATCHrequests also ensures that these requests are always idempotent and therefore safe to retry.Idempotency-Keyis not required for requests using these methods. ↩