Endpoint reference
Find routes, request rules, response fields, and error actions.
The API uses JSON over HTTPS. Add /api/v1 to the origin shown in Developer. Some guides abbreviate routes, such as /projects. Add the /api/v1 prefix once when you build a request URL. Full paths, such as /api/v1/projects, already include it.
Download the OpenAPI 3.1 description for complete endpoint schemas and current permissions. OpenAPI is a machine-readable HTTP interface description.
Find a resource
| Task | Guide |
|---|---|
| Projects, sequences, render estimates, and outputs | Create your first video |
| Upload reservations and asset preparation | Uploads |
| Compositions, captions, AI video, and voiceovers | Create and edit content |
| Editor mutations and searches | Editor tool reference |
| Provider connections, imports, publishing, and team controls | Connect, import, and publish |
| Jobs, retries, credits, and signed events | Jobs and webhooks |
| File sizes, output limits, and feature availability | Limits and recovery |
Requests and responses
Send Content-Type: application/json for a body. JSON bodies must be at most 1 MiB (1,048,576 bytes). Successful responses contain data and requestId. Errors contain error.code, error.message, and requestId. Save the request ID when you need help with a failed request.
Creation, changes, paid work, and retries need Idempotency-Key. This is a request token that prevents duplicate operations. Use a new token for each intended operation. If a request times out, send the same token and body again. The identity includes workspace, method, path, and token. Keys in one workspace share this identity. Changed input returns 409 idempotency_conflict. Never use a new token to bypass an unknown result.
curl "$SOVRAN_API_ORIGIN/api/v1/projects" \
-H "Authorization: Bearer $SOVRAN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: project-2026-10-04-001" \
--data '{"name":"My API project"}'Lists and pagination
Lists use limit from 1 to 100 and an opaque cursor from nextCursor. The default limit is 50. Keep requesting the returned cursor until nextCursor is null. Do not build or change cursor values yourself.
curl "$SOVRAN_API_ORIGIN/api/v1/projects?limit=10" \
-H "Authorization: Bearer $SOVRAN_API_KEY"Handle HTTP errors
| Status | Next action |
|---|---|
400 or 422 | Correct the input identified by the error details. |
401 | Check the host and key. Replace an expired or revoked key in Developer. |
403 | Check permissions, the creator's role, and the current paid plan. |
404 | Check the resource ID and the key's workspace. |
409 | Read error.code. Read current revisions or selection data before changing input. For an uncertain charge or provider result, follow job recovery. |
413 | Reduce the body or file to the permitted size. |
429 | Wait for the duration in Retry-After. Reuse the same token and body for the same operation. |
503 | Check availability. For a temporary read failure, wait and read again. For a mutation, keep the same token and body. |
Workspace keys share request counters. Current tier limits apply to ordinary requests, uploads, rendering, and AI work. An unavailable limit service returns 503.
Admin tools, workers, provider callbacks, checkout, and account deletion are outside this API. Connect provider accounts in the dashboard.