API overview
View as MarkdownThe rules every REST endpoint shares, and the list of endpoints. For one endpoint's fields, open its page in the API reference.
The OpenAPI document
The full schema is an OpenAPI 3.1 document:
https://blitframe.codeartworks.com/openapi/v1.json
The API reference 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:
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. |
| 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 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). |
| Errors | { "error": { "code": "…", "message": "…" } }. Branch on code. See Errors. |
| Retries | Creating a project or variation, editing, importing a ZIP and rendering accept an Idempotency-Key header. See Retrying safely. |
| Rate limits | Requests per minute per workspace, set by your plan: limits.requestsPerMinute in GET /v1/usage. See Limits. |
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 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, 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 |
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: 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 |
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 |
GET POST |
/v1/projects/{projectId}/share-links |
List or create share links |
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 |
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) |
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) |
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, never their secrets |
DELETE |
/v1/api-keys/{apiKeyId} |
Revoke an API key |
POST |
/v1/problem-reports |
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 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, 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) |
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).
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 lists all pages, and the docs' own llms.txt every product's. MCP clients get the same pages as resources. See MCP for agents.