Endpoint reference

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

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

Paged lists use limit from 1 to 100 and an opaque cursor from nextCursor. The default limit is 50. Project composition lists use a default limit of 100. 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"

Use the same page controls for project compositions. This request returns at most one item.

curl "$SOVRAN_API_ORIGIN/api/v1/projects/$PROJECT_ID/compositions?limit=1" \
  -H "Authorization: Bearer $SOVRAN_API_KEY"

A populated page can return a cursor for more items.

{
  "data": {
    "items": [{
      "id": "<COMPOSITION_UUID>",
      "projectId": "<PROJECT_UUID>",
      "title": "Example composition",
      "updatedAt": "2026-10-05T10:00:00.000Z",
      "composition": {
        "version": 1, "aspectRatio": "9:16", "backgroundColor": "#000000",
        "durationInFrames": 30, "fps": 30, "width": 1080, "height": 1920,
        "overlays": []
      }
    }],
    "nextCursor": "1"
  },
  "requestId": "<REQUEST_UUID>"
}

An empty page has no next cursor.

{
  "data": { "items": [], "nextCursor": null },
  "requestId": "<REQUEST_UUID>"
}

Handle HTTP errors

Workspace keys share request counters. Current tier limits apply to ordinary requests, uploads, rendering, and AI work. An unavailable limit service returns 503.

All operations

Use this table to find each endpoint and its required permissions. Some operations also check the saved job, selected tool, or provider connection.

Admin tools, workers, provider callbacks, checkout, and account deletion are outside this API. Connect provider accounts in the dashboard.