API Reference

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.

Base URL

const BASE_URL = "https://api.ittybit.com";

All requests use a base URL of: https://api.ittybit.com

Requests

const response = await fetch(`https://api.ittybit.com/uploads`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    filename: "user-avatar.jpg",
    metadata: {
      user_id: "42",
      user_name: "Douglas Adams",
    },
  }),
});

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.

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....

const response = await fetch(`https://api.ittybit.com/media`, {
  headers: {
    Authorization: `Bearer ${ITTYBIT_API_KEY}`,
  },
});

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.

Responses

{
  "meta":{
    "id": "req_abcdefgh1234",
    "org_id": "org_abcdefgh1234",
    "project_id": "prj_abcdefgh1234",
    "kind": "object",
  },
  "data": {
    "id": "med_abcdefgh1234",
    "kind": "image",
    "url": "https://docs.ittybitcdn.com/med_abcdefgh1234",
    "filesize": 54321,
    // ... other props
  },
  "links": {
    "self": "https://api.ittybit.com/media/med_abcdefgh1234",
    "parent": "https://api.ittybit.com/media",
  }
}

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 resources¹, for example the next page in a list of results, or the parent resource of an object.

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)
• codes in the 5xx range indicate there is an error with Ittybit's service

Errors

{
  "meta":{
    "id": "req_abcdefgh1234",
    "org_id": "org_abcdefgh1234",
    "project_id": "prj_abcdefgh1234",
  },
  "error": {
    "id": "err_abcdefgh1234",
    "name": "NotFound",
    "message": "The requested media item was not found. Please check the URL, that the media ID is correct, and that you have used a valid API Key for the relevant project.",
    "docs": "https://ittybit.com/docs/errors/err_abcdefgh1234",
    "report": "https://ittybit.com/support?kind=error&code=err_abcdefgh1234&request_id=req_abcdefgh1234",
  }
}

If the Ittybit API encounters an error, it will return an error response.

The error response 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.

Pagination

{
  "meta":{
    "id": "req_abcdefgh1234",
    "kind": "list",
    "limit": 12,
    "total": 20,
    "page": 1,
    "pages": 2
  },
  "data": [
    // { ... media object },
    // { ... media object },
    // ... etc
  ],
  "links": {
    "self": "https://api.ittybit.com/media",
    "next": "https://api.ittybit.com/media?page=2",
    "prev": null,
  }
}

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.

Idempotency

We deduplicate POST 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.

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.

Versioning

const response = await fetch(`https://api.ittybit.com/media`, {
  headers: {
    "Accept-Version": "2025-05-01",
    // ... other headers
  },
});

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": "2025-05-01".

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.

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.