API overview

View as Markdown

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