# API Reference


Ittybit REST API

Base URL: `https://api.ittybit.com`

Process video, audio, and images via HTTP. Create jobs for full pipelines, or compose individual tasks for custom workflows. For local processing, see the [CLI](/cli).

## Authentication

```
Authorization: Bearer ittybit_live_...
```

All requests require an API key. Requests without a valid key return `401`.

## Endpoints

| Method | Path                         | Description              |
| ------ | ---------------------------- | ------------------------ |
| `POST` | [`/jobs`](/api/create-job)   | Create a processing job  |
| `GET`  | [`/jobs`](/api/list-jobs)    | List jobs                |
| `GET`  | [`/jobs/{id}`](/api/get-job) | Get job with tasks       |
| `POST` | [`/tasks`](/api/create-task) | Create a standalone task |

## Responses

Success returns the resource directly. Errors return `kind` + `message`:

```json
{ "kind": "invalid_input", "message": "input must use http://, https://, or s3:// scheme" }
```

## Pagination

List endpoints like [GET /jobs](/api/list-jobs) support cursor-based pagination.

| Param    | Description                      |
| -------- | -------------------------------- |
| `limit`  | 1–100 (default 20)               |
| `after`  | Return items after this ID       |
| `before` | Return items before this ID      |
| `order`  | `asc` or `desc` (default `desc`) |

## Idempotency

`POST` endpoints accept `Idempotency-Key` header. Same key within 24h returns the original response with `200`. Useful for safely retrying requests without creating duplicate jobs.

## Timestamps

All timestamps are Unix milliseconds (integers).

## See also

- [CLI Reference](/cli) — process files locally with the same options
- [Convert uploads for web playback](/guides/web-video)
- [Extract thumbnails from video](/guides/thumbnail)
- [Extract audio from video](/guides/extract-audio)