REST API

Conventions

Response shapes, errors, headers, bodies, pagination, replays, retries, ids and health probes.

Read as Markdown

The rules every /api/v1 endpoint follows. Learn them once.

Success is bare

Fields sit at the top level next to ok: true. No data wrapper.

Response: 200 (trimmed)
{
  "ok": true,
  "actors": [
    {
      "actor_id": "act_0193c8f0a1b24e7f9d3c5a6b7e8f0011",
      "name": "Maya",
      "gender": "female",
      "default_voice_id": "voc_0193c8f0a1b24e7f9d3c5a6b7e8f0022",
      "is_platform": true
    }
  ],
  "next_cursor": "eyJpc09yZyI6dHJ1ZSwiaXNDb3JlIjpmYWxzZX0"
}
  • Wire fields are snake_case.
  • Exception: fields inside config come from the capability schema and can be camelCase (voiceId). Read config_schema from GET /capabilities/{id}.

Answers are written for people

Every answer holds only the final details a person needs, so you can show it in your own product as it is.

WhatWhere
Where things stand, in one or two plain sentencessummary, on estimates, submits, reads, waits, batches, runs and the balance
The price beforecredits and is_ceiling on an estimate
The charge aftercredits_charged (null until final) and charge_summary
A fileOne link, url: permanent and public. See Download links
  • Show summary and charge_summary as they are. Never parse them: the wording can change.
  • max_credits_needed is for your next call, not for the person: Price first.

Errors are wrapped

A refusal is one object inside error, the same on every route.

Response: 402
{
  "error": {
    "ok": false,
    "code": "insufficient_credits",
    "message": "Not enough credits for this request. What each plan includes is described at riffads.com/pricing.",
    "retryable": false,
    "credits_charged": 0,
    "shortfall": 240
  }
}
  • Branch on code and retryable. Never on message: its wording can change.
  • Some codes add fields, such as shortfall, retry_after_seconds, limit or in_flight. A field that does not apply is left out, never null.
  • No errors array, no details object. Every field and code: The error body.
  • The two health probes are the only routes that answer in another shape.

HTTP status

The status comes from the code, and it is the same everywhere. The ones that surprise people:

  • workspace_unavailable is 410, not 403.
  • moderation_blocked is 422.
  • insufficient_scope is 403, not 401.
  • Three codes are 429: rate_limited (retry), quota_exceeded (don't), request_blocked (don't).
  • Another workspace's id answers 404 not_found, never forbidden.
  • An unknown /api/v1 path answers 404 not_found in the envelope, with no key check. A wrong method on a real path is a plain 405.

Response headers

HeaderWhenValue
Cache-ControlEvery responseno-store
Content-TypeEvery responseapplication/json
Retry-AfterA 429 with retry_after_secondsThe same integer as the body
WWW-AuthenticateEvery 401Bearer realm="RiffAds"
LocationThe 201 from POST /generations and both invoke routes/api/v1/generations/{id} or /api/v1/workflow-runs/{id}
  • That is the full list. No X-RateLimit-*, no request id, no version header.
  • POST /uploads, POST /uploads/from-url and POST /webhooks return 201 without Location.

Request bodies are strict

Send a JSON object with Content-Type: application/json. An unknown key is refused, never ignored, inside config too.

Response: 400
{
  "error": {
    "ok": false,
    "code": "invalid_config",
    "message": "That request body is not valid. max_credits: Invalid input: expected number, received undefined; Unrecognized key: \"maxCredits\".",
    "retryable": false,
    "credits_charged": 0
  }
}
CauseMessage
Not JSONThat request body is not valid JSON. Send a JSON object and set Content-Type: application/json.
null, array or scalarThat request body is not a JSON object. Send an object with the documented fields at its top level.
Fails the schemaThat request body is not valid. {path}: {issue}; {path}: {issue}. Up to 5 issues, then Plus N more.
  • Refused in any body: project_id, organization_id, idempotency_key, source, quote, and any webhook or callback field.
  • Invoke bodies also refuse workflow_id and template_key.
  • POST /estimates checks config exactly as POST /generations does. A 400 on the estimate means the submit would fail too.

Deprecated properties

A config_schema property marked "deprecated": true is an old name for a renamed field. It works until the version its description names.

  • Send the new name. The description says which one.
  • Never send both. Both names at once is 400 invalid_config.
  • How long an old name lasts: Stability.

Query params are lenient

A param that can't be read counts as omitted, not as an error.

You sendServer reads
?limit=2525
?limit=abc, ?limit=, ?limit=0, ?limit=-3, ?limit=2.5Omitted, the default applies
?limit=1000Clamped to the max
?search=%20%20Omitted
?search=%20maya%20maya

Pagination

Cursor only: no page, offset, per_page or after. Every paged list takes limit (default 25, max 50) and cursor: Page sizes.

EndpointFilterstotal
GET /capabilitiesnoneyes
GET /actorssearchno
GET /voicessearch, languageyes
GET /generationsstatus, capability_id, source, created_before, updated_sinceno
GET /assetsq, kind, aspect_ratio, originno
GET /presetsnoneyes
GET /workflow-runs, GET /workflows/{id}/runsstatus, sourceno
Terminal
curl -sG https://app.riffads.com/api/v1/capabilities \
  -H "Authorization: Bearer $RIFFADS_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "cursor=$NEXT_CURSOR"

The list rule

The same for every paged list:

  • A page can be shorter than limit. Only next_cursor: null means the end. Never stop on a short or empty page.
  • Pass next_cursor back as cursor, exactly, with the same filters. Don't parse it, build it, or reuse it across filters.
  • A stale or bad cursor restarts from page one. It never returns an error.
  • total, where present, counts rows this workspace can see, after filters.
  • Lists return ids, never links. The one exception is a preset template's preview_url, which is permanent public art. Download links.

Not paged, returns everything: GET /workflows/templates, GET /batches/{id}, GET /workflow-runs/{id}, GET /presets/{id}/templates, GET /webhooks (10 at most).

Idempotency and replays

There is no Idempotency-Key header and no idempotency_key field. Sending the field is a 400.

Two identical submits can mean two jobs

Resending a submit after the first job finished starts a new, paid job. Lost the response? Read the generation, never resubmit to find out.

A submit that matches a job still running in this workspace does not start a second one. You get the running job back, and the summary says it was not charged twice.

Response: 201
{
  "ok": true,
  "generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033",
  "generation_ids": ["gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033"],
  "outputs_expected": 1,
  "summary": "This request was already started, so it is not charged twice.",
  "next_action": "This exact request was already running in this workspace, so RiffAds handed back the generation that is already going ..."
}
  • A replay is still 201 with Location, pointing at the job that was already running. Nothing new is charged.
  • Only while the first job is queued, rendering or post_processing, and never for variants that fan out into a batch.
  • The identical request running for someone else in the workspace gets 409 submission_in_flight with retry_after_seconds: 30 instead.

Retries

Branch on retryable, not on the HTTP status: Refusals and retries. A retry loop: Errors.

Blocked requests

The same exact request failing again and again goes on a block list. The block is keyed on the request (workspace, capability, actor, voice, uploads, config), not on you.

  • 3 failures from provider_unavailable, internal_error or some content refusals pause it for about 1 hour, with retry_after_seconds.
  • 2 content refusals block it for 30 days.
  • Blocked: 429 request_blocked, retryable: false, with blocked_reason naming the code that caused it.
  • Adding junk fields won't escape a block. Change the script or the inputs.
  • A successful submit clears the flags for that request. Money refusals never arm a block.

next_action is advice

Submits, waits, uploads, invokes and run reads carry next_action: a sentence written for an AI agent. Never branch code on it: branch on still_running and status.

Some next_action sentences name MCP tools, even over REST. The matching REST route: Same job, every surface.

Ids and timestamps

  • Ids carry a prefix: gen_, bg_, act_, voc_, ast_, wf_, wfr_, wh_, whd_, and captpl_ for a preset template. Full list: Id prefixes.
  • Timestamps are ISO 8601 UTC: 2026-09-17T10:04:11.482Z.

OpenAPI

The contract is an OpenAPI 3.1 file, built from the same schemas the API checks requests with. No key needed.

The same file is also served here:

Health

Two probes for uptime monitors and load balancers. No key, and not the error envelope.

EndpointChecksBrake
GET /healthNothing. The API process answeredNone
GET /health/readyOne database query, with a 3 second timeout60 requests a minute per IP address
  • Both send Cache-Control: no-store and ignore a key sent anyway. No version, commit or region in either body.
  • Branch on the HTTP status first (200, 429 or 503), then on status. There is no error.code and no retryable here.

Liveness

GET/api/v1/healthNo auth

Is the API up? A timeout or a 5XX from the platform in front means it is down.

Response: 200
{
  "ok": true,
  "status": "ok",
  "service": "riffads-api"
}

Readiness

GET/api/v1/health/readyNo auth

Can the API serve a real request? It runs one database query.

Response: 200
{
  "ok": true,
  "status": "ready",
  "checks": {
    "database": "ok"
  }
}
Response: 503
{
  "ok": false,
  "status": "unavailable",
  "checks": {
    "database": "down"
  }
}
  • 503 when the query fails or takes longer than 3 seconds. The reason is never in the body.
  • It checks the database only. A model provider outage shows on the generation (provider_unavailable), not here.
  • A healthy probe does not mean your key works. Test the key with a cheap read, such as GET /capabilities.

The IP brake

Over 60 requests a minute from one IP address, /health/ready answers 429 with Retry-After in seconds. /health is never braked.

Response: 429
{
  "error": "too_many_requests",
  "error_description": "Too many requests from this address. Please wait and try again."
}

A 429 here means your monitors poll too often from one address. It is not an outage.

Terminal
# Every 30 seconds: is the API up?
curl -sf https://app.riffads.com/api/v1/health > /dev/null || echo "RiffAds API down"

# Every 2 minutes: can it serve a request?
code=$(curl -s -o /dev/null -w "%{http_code}" https://app.riffads.com/api/v1/health/ready)
[ "$code" = "200" ] || echo "RiffAds API not ready ($code)"

Not in the API

  • No per-request webhook. Register an endpoint once with POST /webhooks: Webhooks.
  • No SSE or websockets. Use the wait endpoint, a webhook, or both.
  • No SDK. Generate a client from the OpenAPI file, or call the API directly.
  • No test keys. sk_live_ only.
  • No cancel, no key management, no brand or product routes. Those live in the app.
  • No workflow authoring. No route creates, edits or deletes a graph.

What RiffAds never does: What RiffAds does not do.

On this page