Core concepts

Envelopes & errors

The response shapes every endpoint shares, and the error contract.

Success shapes

Success bodies are the resource shape directly. Creations return 201, reads and updates return 200, and deletes return 204 with no body. Async dispatches return 202 with the job envelope.

The list envelope

Every list endpoint responds with the same wrapper:

list

{
  "data": [ { "id": "..." }, { "id": "..." } ],
  "total": 42,
  "cursor": "eyJvZmZzZXQiOjIwfQ"
}

cursor appears only when more pages exist; pass it back to continue. See Pagination.

The job envelope

Long-running work returns a job you poll at GET /jobs/{id}:

job

{
  "jobId": "vid_6870f3...",
  "type": "video",
  "status": "processing",
  "rawStatus": "visuals",
  "pollUrl": "/api/v1/jobs/vid_6870f3...",
  "progressMessage": "Rendering scenes"
}

Full details in Jobs & polling.

The error envelope

Errors are always one shape, with a stable machine code:

error

{
  "error": {
    "code": "not_found",
    "message": "Webhook not found",
    "requestId": "req_2f6a..."
  }
}

Common statuses

400

bad request

Validation failed; the message names the field.

401

unauthorized

Missing or invalid API key.

403

forbidden

The key lacks the required scope, or the plan lacks API access.

404

not found

Unknown resource. Non-owned resources also return 404 (enumeration-safe).

429

rate limited

Per-key rate limit exceeded; retry after backing off.

5xx

server error

Something failed on our side; safe to retry idempotent requests.

Request ids

Every response, success or error, carries an X-Request-Id header (mirrored as requestId inside error bodies). Log it and quote it in support requests so we can trace the exact call.