# API overview

The rules every REST endpoint shares, and the list of endpoints. For one endpoint's fields, open its page in the [API reference](/reference/blitframe).

## The OpenAPI document

The full schema is an OpenAPI 3.1 document:

```
https://blitframe.codeartworks.com/openapi/v1.json
```

The [API reference](/reference/blitframe) shows it with one page per endpoint: its parameters and its request and response fields. Each page has a request in curl, Python, Node.js, PHP, Ruby, Go, C# and Java. **Try it** on an endpoint's page sends the request from your browser with your API key. The key is not saved: type it again on the next page.

You can also import the document into Postman or Insomnia, or generate a client:

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://blitframe.codeartworks.com/openapi/v1.json -g python -o blitframe-client
```

## Conventions

| Topic | Rule |
|---|---|
| Base URL | `https://blitframe.codeartworks.com/v1` |
| Authentication | `Authorization: Bearer <api key>` on every request. See [Authentication and API keys](/docs/blitframe/authentication). |
| Format | JSON request and response bodies, UTF-8, camelCase fields |
| Ids | UUID strings. Share link ids are the exception (22-character URL-safe strings), and so are library font slugs. |
| Enums | camelCase strings, such as `"mp4"`, `"extraHigh"` and `"succeeded"`. Webhook [event types](/docs/blitframe/webhooks#events) are the exception: dotted, lower-case names such as `"render.succeeded"` and `"download_archive.ready"`. |
| Times | ISO 8601 with offset, such as `2026-11-04T14:00:00+00:00` |
| Empty fields | Sent as `null`, never left out. The exceptions are three fields of a render: `replacements`, which only the responses of `POST /v1/renders` and `GET /v1/renders/{renderId}` carry, and only when the render has some, `codec`, left out for frame renders, and `encoding`, left out unless the render asked for its own settings ([render fields](/docs/blitframe/renders#create-a-render)). |
| Errors | `{ "error": { "code": "…", "message": "…" } }`. Branch on `code`. See [Errors](/docs/blitframe/errors). |
| Retries | Creating a project or variation, editing, importing a ZIP and rendering accept an `Idempotency-Key` header. See [Retrying safely](#retrying-safely). |
| Rate limits | Requests per minute per workspace, set by your plan: `limits.requestsPerMinute` in `GET /v1/usage`. See [Limits](/docs/blitframe/limits#api-and-workspace). |

## Lists

| Part | Rule |
|---|---|
| Response | `{ "items": [...], "next": "…" }` |
| Next page | Pass `next` as `before`. Project files and library fonts take it as `after` instead. |
| Last page | `next` is `null`. |
| A wrong cursor | A `before` that is not a `next` value from the same list is `400 invalid_request`. |

## Wait for a result

Some requests can hold their response until the work is done. [Waiting for a result](/docs/blitframe/renders#waiting-for-a-result) explains the header.

| Request | Waits |
|---|---|
| `GET /v1/renders/{renderId}`, download archives, version exports, ZIP import status (`GET /v1/projects/{projectId}/package/{importId}`), `GET /v1/uploads/{uploadId}` and `POST /v1/uploads/{uploadId}/complete` | Only with `Prefer: wait=N`, for up to 50 seconds |
| `POST /v1/projects` with a ZIP upload, and `POST /v1/projects/{projectId}/package` | Up to 50 seconds for the import by default. `Prefer: wait=N` sets a shorter wait. |

## Endpoints

| Method | Path | Does |
|---|---|---|
| `GET` | `/v1/projects?q=&copiedFromVersionId=&copiedFromProjectId=&limit=100&before=` | List projects, newest first. `q` searches names, `copiedFromVersionId` and `copiedFromProjectId` find [copies](/docs/blitframe/projects#duplicating-a-project), and `next` passed as `before` gets older ones. |
| `POST` | `/v1/projects` | Create a project: empty, from a ZIP upload, or as a [copy of a version](/docs/blitframe/projects#duplicating-a-project) |
| `GET` `PATCH` `DELETE` | `/v1/projects/{projectId}` | Get, rename or delete a project |
| `GET` | `/v1/projects/{projectId}/files` | Distinct files across the project's versions |
| `GET` | `/v1/projects/{projectId}/versions` | Version history, newest first, from the head of `main` or of `?variation=` |
| `POST` | `/v1/projects/{projectId}/versions` | [Edit the project](/docs/blitframe/projects#editing-a-project): a new version that becomes the head of `main`, or of the `variation` named |
| `POST` | `/v1/projects/{projectId}/package` | Import a ZIP upload as a new version |
| `GET` `POST` | `/v1/projects/{projectId}/variations` | List or create [variations](/docs/blitframe/variations) |
| `GET` `DELETE` | `/v1/projects/{projectId}/variations/{name}` | Get or delete a variation |
| `GET` | `/v1/projects/{projectId}/package/{importId}` | Status of a large ZIP import, kept 7 days after it finishes |
| `POST` | `/v1/projects/{projectId}/renders/batch` | Queue up to 1,000 renders of one version, each with its own [replacements](/docs/blitframe/editing#many-videos-from-a-data-sheet) |
| `GET` `POST` | `/v1/projects/{projectId}/share-links` | List or create [share links](/docs/blitframe/sharing) |
| `DELETE` | `/v1/share-links/{linkId}` | Revoke a share link |
| `GET` | `/v1/versions/{versionId}` | Get a version with its files and problems |
| `GET` | `/v1/versions/{versionId}/layers` | Editable text, image and video layers |
| `GET` | `/v1/versions/{versionId}/files/{path}` | Download one file (302 redirect) |
| `POST` | `/v1/versions/{versionId}/export` | Queue a ZIP of the whole version |
| `GET` | `/v1/versions/{versionId}/export/{exportId}` | Export status and download link |
| `POST` | `/v1/uploads` | Presigned upload for a large file or ZIP (multipart above 100 MB) |
| `POST` | `/v1/uploads/{uploadId}/parts` | Fresh URLs for parts of a multipart upload |
| `POST` | `/v1/uploads/{uploadId}/complete` | Complete an upload, which starts its check |
| `GET` `DELETE` | `/v1/uploads/{uploadId}` | Upload status (`ready` once checked), or discard an upload |
| `GET` | `/v1/files/capabilities` | Supported file types and their limits |
| `POST` | `/v1/renders` | Queue a render of a project's head or of a version, optionally with [replacements](/docs/blitframe/editing#in-a-render) |
| `GET` | `/v1/renders` | List renders |
| `GET` | `/v1/renders/{renderId}` | Render status and output links |
| `POST` | `/v1/renders/statuses` | Status of up to 1,000 renders |
| `POST` | `/v1/renders/cancel` | Cancel up to 1,000 renders (see [refunds](/docs/blitframe/renders#pricing)) |
| `POST` | `/v1/renders/download-archive` | ZIP of up to 1,000 succeeded videos |
| `GET` | `/v1/renders/download-archive/{archiveId}` | Archive status and download link |
| `POST` | `/v1/renders/{renderId}/cancel` | Cancel a render (see [refunds](/docs/blitframe/renders#pricing)) |
| `DELETE` | `/v1/renders/{renderId}` | Delete a finished render and its output files |
| `GET` | `/v1/renders/{renderId}/html` | Package a render as an HTML5 ad |
| `GET` | `/v1/usage` | Plan, render-second balance and plan limits |
| `GET` | `/v1/fonts` | Search library fonts (`q`, `limit`, `after`) |
| `GET` | `/v1/fonts/{slug}` | One library font with its license and preview image |
| `GET` | `/v1/api-keys` | List [API keys](/docs/blitframe/authentication), never their secrets |
| `DELETE` | `/v1/api-keys/{apiKeyId}` | Revoke an API key |
| `POST` | `/v1/problem-reports` | [Report a problem](/docs/blitframe/renders#report-a-problem) with a render or version |
| `GET` | `/v1/problem-reports/{reportId}` | A problem report, and whether it is resolved |
| `GET` `POST` | `/v1/webhooks` | List or add [webhook](/docs/blitframe/webhooks) endpoints |
| `GET` `PATCH` `DELETE` | `/v1/webhooks/{webhookId}` | Get, update (url, events or allEvents, enabled, description) or remove an endpoint |
| `POST` | `/v1/webhooks/{webhookId}/rotate-secret` | New signing secret. The previous one keeps signing for `gracePeriodSeconds` (default 24 hours, 0 to stop at once). |
| `GET` | `/v1/webhooks/{webhookId}/deliveries` | Delivery log of the last 30 days |
| `POST` | `/v1/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver` | Send a delivery's event again, with the same `webhook-id` |
| `POST` | `/v1/webhooks/{webhookId}/test` | Send a `webhook.test` event |
| `POST` | `/v1/webhooks/{webhookId}/recover` | Resend, once each, the events that never reached the endpoint (`since` optional) |

Billing, the team and sign-in security are managed in the [console](https://app.codeartworks.com/blitframe/), not through the API. The API can list and revoke API keys, but new keys come from the console.

## Retrying safely

A request can time out, or its response can be lost, after Blitframe has done the work. To retry it without doing the work twice, send an `Idempotency-Key` header with a unique value of your own, such as a UUID. Send the same key again when you retry.

| Request | A retry with the same key returns |
|---|---|
| `POST /v1/projects` | The project the first request created, or the import creating it from a ZIP |
| `POST /v1/projects/{projectId}/versions` | The version the edit made |
| `POST /v1/projects/{projectId}/package` | The version the import made. If the first request's response was `202`, the import as it is now. |
| `POST /v1/projects/{projectId}/variations` | The variation |
| `POST /v1/renders` | The render, charged once ([render keys](/docs/blitframe/renders#idempotency)) |
| `POST /v1/projects/{projectId}/renders/batch` | The batch's renders, charged once |

What a key does in each case:

| Case | Response |
|---|---|
| The same request again, after the first succeeded | The first request's status and what it made, as it is now, with the header `Idempotent-Replayed: true`. Nothing is created, queued or charged again. Whitespace and the order of fields don't make a request different. |
| A different request with the same key | `422 idempotency_key_reused`, while what the first request made exists. Use a new key for each new request. |
| The same key while the first request is still running | `409 idempotency_key_in_use`. Wait, then send it again with the same key. Renders and batches wait for the first request instead, then return its renders. A ZIP import waits for the import the first request started, as that request does. |
| The first request failed | It made nothing, so send it again with the same key. |

| Key rule | Detail |
|---|---|
| How long a key lasts | 24 hours. A key is forgotten sooner when what it made is gone: the project or variation was deleted, the ZIP import failed, or a single render was deleted. Then the key is free for any request. |
| Batches | A batch's key is forgotten only once all its renders are deleted. While some remain, the same key gets `422 idempotency_key_reused`. |
| Format | 1 to 200 characters. A render's or batch's key also has no `/` and does not start with `share:`. An empty key, or one that breaks these rules, is `400 invalid_request`. |
| Scope | A key belongs to your workspace and to one kind of request (single renders and batches count as one kind). For edits, imports and variations, it also belongs to one project. |
| MCP | MCP tools take the same keys as `idempotencyKey`. |

An edit that names uploads is safe to send again even without a key. Once its uploads are used, the same edit returns the version it made ([editing a project](/docs/blitframe/projects#editing-a-project)).

## Documentation for agents

Every docs page is also plain Markdown at `/docs/blitframe/{page}.md`, and each of its sections at `/docs/blitframe/{page}/{section}.md`, for example `/docs/blitframe/data-json-format/text-and-fonts.md`. [llms.txt](/docs/blitframe/llms.txt) lists all pages, and [the docs' own llms.txt](/docs/llms.txt) every product's. MCP clients get the same pages as resources. See [MCP for agents](/docs/blitframe/mcp).
