Conventions
Response shapes, errors, headers, bodies, pagination, replays, retries, ids and health probes.
Read as MarkdownThe 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.
{
"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
configcome from the capability schema and can be camelCase (voiceId). Readconfig_schemafromGET /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.
| What | Where |
|---|---|
| Where things stand, in one or two plain sentences | summary, on estimates, submits, reads, waits, batches, runs and the balance |
| The price before | credits and is_ceiling on an estimate |
| The charge after | credits_charged (null until final) and charge_summary |
| A file | One link, url: permanent and public. See Download links |
- Show
summaryandcharge_summaryas they are. Never parse them: the wording can change. max_credits_neededis 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.
{
"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
codeandretryable. Never onmessage: its wording can change. - Some codes add fields, such as
shortfall,retry_after_seconds,limitorin_flight. A field that does not apply is left out, nevernull. - No
errorsarray, nodetailsobject. 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_unavailableis 410, not 403.moderation_blockedis 422.insufficient_scopeis 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/v1path answers404 not_foundin the envelope, with no key check. A wrong method on a real path is a plain405.
Response headers
| Header | When | Value |
|---|---|---|
Cache-Control | Every response | no-store |
Content-Type | Every response | application/json |
Retry-After | A 429 with retry_after_seconds | The same integer as the body |
WWW-Authenticate | Every 401 | Bearer realm="RiffAds" |
Location | The 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-urlandPOST /webhooksreturn 201 withoutLocation.
Request bodies are strict
Send a JSON object with Content-Type: application/json. An unknown key is refused, never ignored, inside config too.
{
"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
}
}| Cause | Message |
|---|---|
| Not JSON | That request body is not valid JSON. Send a JSON object and set Content-Type: application/json. |
null, array or scalar | That request body is not a JSON object. Send an object with the documented fields at its top level. |
| Fails the schema | That 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_idandtemplate_key. POST /estimateschecksconfigexactly asPOST /generationsdoes. 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 send | Server reads |
|---|---|
?limit=25 | 25 |
?limit=abc, ?limit=, ?limit=0, ?limit=-3, ?limit=2.5 | Omitted, the default applies |
?limit=1000 | Clamped to the max |
?search=%20%20 | Omitted |
?search=%20maya%20 | maya |
Pagination
Cursor only: no page, offset, per_page or after. Every paged list takes limit (default 25, max 50) and cursor: Page sizes.
| Endpoint | Filters | total |
|---|---|---|
GET /capabilities | none | yes |
GET /actors | search | no |
GET /voices | search, language | yes |
GET /generations | status, capability_id, source, created_before, updated_since | no |
GET /assets | q, kind, aspect_ratio, origin | no |
GET /presets | none | yes |
GET /workflow-runs, GET /workflows/{id}/runs | status, source | no |
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. Onlynext_cursor: nullmeans the end. Never stop on a short or empty page. - Pass
next_cursorback ascursor, 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.
{
"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
201withLocation, pointing at the job that was already running. Nothing new is charged. - Only while the first job is
queued,renderingorpost_processing, and never forvariantsthat fan out into a batch. - The identical request running for someone else in the workspace gets
409 submission_in_flightwithretry_after_seconds: 30instead.
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_erroror some content refusals pause it for about 1 hour, withretry_after_seconds. - 2 content refusals block it for 30 days.
- Blocked:
429 request_blocked,retryable: false, withblocked_reasonnaming 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_, andcaptpl_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.
| Endpoint | Checks | Brake |
|---|---|---|
GET /health | Nothing. The API process answered | None |
GET /health/ready | One database query, with a 3 second timeout | 60 requests a minute per IP address |
- Both send
Cache-Control: no-storeand 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 noerror.codeand noretryablehere.
Liveness
GET/api/v1/healthNo auth
Is the API up? A timeout or a 5XX from the platform in front means it is down.
{
"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.
{
"ok": true,
"status": "ready",
"checks": {
"database": "ok"
}
}{
"ok": false,
"status": "unavailable",
"checks": {
"database": "down"
}
}503when 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.
{
"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.
# 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.