Workflows
List templates, run one, read the run node by node, and list past runs.
Read as MarkdownRun a template or a saved workflow from code, then read the run until it ends. What each template makes: Workflow templates.
Agents run workflows, they don't build them
No route creates, edits or deletes a graph. Build workflows in the app at app.riffads.com, run them from code.
Routes
| Endpoint | Scope | Limit per key | What it does |
|---|---|---|---|
GET /workflows/templates | Read | 120 a minute | Templates you can run, with fillable node ids |
POST /workflows/templates/{key}/invoke | Workflows | 20 a minute | Runs a template |
POST /workflows/{id}/invoke | Workflows | 20 a minute | Runs a workflow your workspace owns |
GET /workflow-runs/{id} | Read | 120 a minute | One run, node by node |
GET /workflow-runs | Read | 120 a minute | Every run in this workspace, newest first |
GET /workflows/{id}/runs | Read | 120 a minute | One workflow's runs, newest first |
- Every key can read. Invokes need the Workflows scope, set when the key is created, or get
403 insufficient_scope: Authentication. - All limits: Limits.
The loop
List templates
GET/api/v1/workflows/templatesAPI keyNo params, no paging. Templates your plan can't run are left out.
curl -s https://app.riffads.com/api/v1/workflows/templates \
-H "Authorization: Bearer $RIFFADS_API_KEY"{
"ok": true,
"templates": [
{
"template_key": "ugc_face_cam",
"name": "Creator to camera",
"step_count": 8,
"inputs": [
{
"node": "f_brand",
"label": "Your brand",
"field": "text",
"field_label": "value",
"kind": "text",
"max_length": 8000,
"filled": true
},
{
"node": "f_video",
"label": "The talking ad",
"field": "voice",
"field_label": "Voice",
"kind": "voice",
"filled": false
}
]
}
]
}Invoke
POST/api/v1/workflows/templates/{key}/invokeAPI keyPOST/api/v1/workflows/{id}/invokeAPI keySame body, same response. The path names the graph. Save the body as body.json:
{
"max_credits": 1200,
"inputs": [
{
"node": "f_brand",
"field": "text",
"value": "Brand: Tidely\nProduct: cold brew concentrate, a 32 oz glass bottle\nCreator: a man in his early thirties who works from home"
},
{
"node": "f_video",
"field": "voice",
"value": "voc_0193c8f0a1b24e7f9d3c5a6b7e8f0099"
}
]
}Then send it:
curl -i -X POST https://app.riffads.com/api/v1/workflows/templates/ugc_face_cam/invoke \
-H "Authorization: Bearer $RIFFADS_API_KEY" \
-H "Content-Type: application/json" \
-d @body.json{
"ok": true,
"workflow_run_id": "wfr_0193c8f0a1b24e7f9d3c5a6b7e8f0077",
"workflow_id": "wf_0193c8f0a1b24e7f9d3c5a6b7e8f0055",
"template_key": "ugc_face_cam",
"applied_inputs": [
{
"node": "f_brand",
"field": "text"
},
{
"node": "f_video",
"field": "voice"
}
],
"credits_estimated": 990,
"summary": "Started. It takes a few minutes and costs up to 990 credits.",
"next_action": "This run has 7 steps to work through and takes minutes, not seconds. ..."
}The 201 carries Location: /api/v1/workflow-runs/{workflow_run_id}. Numbers are examples, not prices.
credits_estimatedis the most the run is expected to cost. What it really cost iscredits_chargedon the run, once it ends.summarysays the same in plain words, ready to show a person.
Read the run
GET/api/v1/workflow-runs/{id}API keyIt never blocks. Read it about every 30 seconds until run.still_running is false.
curl -s https://app.riffads.com/api/v1/workflow-runs/wfr_0193c8f0a1b24e7f9d3c5a6b7e8f0077 \
-H "Authorization: Bearer $RIFFADS_API_KEY"- Rather be told than poll? Subscribe a webhook to
workflow_run.completedandworkflow_run.failed. - The same jobs on MCP and the CLI: Same job, every surface.
Template fields
| Field | Type | Notes |
|---|---|---|
template_key | string | The {key} in the invoke path |
name, description, category | string | The last two can be null. Never branch on category |
step_count | integer | Every node except canvas notes: the most steps that can run and charge |
inputs | array | One entry per text field, open setting, actor slot and voice slot you may set |
Input slots
| Field | What it is |
|---|---|
node | Node id to use in inputs. Use it exactly |
label | Node name, for people |
field | Field on that node to fill |
field_label | Field name as people see it. A text box shows as value |
kind | text, setting, actor or voice |
accepts | Settings only: the legal values, in words |
max_length | Text only: the character limit |
filled | true if the node already holds a value (usually example copy) |
You can't guess node ids. Read them from this list: a wrong one is refused before anything starts.
Invoke body
| Field | Type | Required | Rules |
|---|---|---|---|
max_credits | integer | yes | Above zero. The most the whole run may cost |
inputs | array | no | At most 60 entries |
inputs[].node | string | yes | Node id from the template list or a run you read |
inputs[].field | string | yes | Field name on that node |
inputs[].value | string, number or boolean | yes | Scalar only. No objects, arrays or null |
Strict: an unknown key is 400 invalid_config. There is no workflow_id or template_key body field.
Sizing max_credits
- There is no run estimate:
POST /estimatesprices one config, not a graph. max_creditscaps all steps added up. Too low:402 max_credits_exceeded, nothing starts, andlimit.required_creditssays what the run needs.- Don't reuse
credits_estimatedasmax_credits. It is usually lower than the totalmax_creditsis checked against. - Agent spend limits apply to runs too: Spend limits.
What inputs can set
- Text must fit
max_length. A setting must be one of the valuesacceptslists. - An
actorslot takes anact_id fromGET /actors, avoiceslot avoc_id fromGET /voices. - Inputs change this run only. The saved workflow never changes.
- All or nothing: one bad entry refuses the call. A later entry for the same field wins.
- Creator to camera needs only
f_brand: the voice onf_videois matched to the face it invents. Send avoiceonly to use the same one every run: Workflow templates.
Input refusals
All are 400 invalid_config with a message that says what to send instead, except an actor or voice id you can't use (404 not_found).
- An unknown node or field. The message lists what the node takes.
- A wired field (fed by another node). The message names the node to set instead.
count, which is never writable.- Empty text. Leave the field out to keep the template value.
- Text over
max_length, or a setting valueacceptsdoes not list. - A file. Values are scalar and file slots are not exposed.
Invoking by template key
- The first run makes your workspace's copy: one workflow per template, named
<template name> (agent). Later runs of that key reuse it. - The copy keeps the template's node ids. Its
workflow_idis in the response, and invoking that id runs the same graph. - Delete the copy in the app and the next run makes a fresh one.
- One run at a time per workflow. A second invoke while it runs gets
409 submission_in_flight. Different workflows can run at once. - A run is refused while this key has a generation in flight. A generation is not refused while the key has a run in flight.
- An unknown key and a key that is not live both answer
404 not_found.
Reading a run
{
"ok": true,
"run": {
"workflow_run_id": "wfr_0193c8f0a1b24e7f9d3c5a6b7e8f0077",
"workflow_id": "wf_0193c8f0a1b24e7f9d3c5a6b7e8f0055",
"status": "completed",
"still_running": false,
"summary": "Your result is ready. Charged 552 credits.",
"nodes": [
{
"node_id": "f_video",
"label": "The talking ad",
"status": "completed",
"generations": [
{
"generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033",
"status": "completed",
"summary": "Your video is ready. Charged 544 credits.",
"outputs": [
{
"index": 0,
"kind": "video",
"asset_id": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044",
"url": "https://app.riffads.com/files/ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044?key=q7Hk2mX9pLr4TzVb8NcW1a",
"file_name": "Generation 7e8f0033",
"width": 720,
"height": 1280
}
],
"credits_charged": 544
}
],
"text": null,
"error": null
}
],
"credits_estimated": 990,
"credits_charged": 552,
"credits_left": 8133,
"started_at": "2026-09-17T10:04:11.482Z",
"finished_at": "2026-09-17T10:12:02.900Z"
},
"next_action": "This run is finished and credits_charged is final. Give the person each file's url: ..."
}Each generations entry has the shape of GET /generations/{id}: Generations.
| Field | Type | Notes |
|---|---|---|
run.status | string | queued, running, completed, partial, failed, canceled |
run.still_running | boolean | false for the last four. Poll on this |
run.summary | string | Where the run stands, in plain words. Show it as it is |
run.nodes[].node_id | string | The same id inputs uses |
run.nodes[].status | string | pending, ready, dispatching, running, completed, failed, skipped, canceled |
run.nodes[].generations | array | The node's generations, each file with its url. Empty until the node runs |
run.nodes[].text | string | null | A writer node returns text, no file |
run.nodes[].error | object | null | An object with code and message. code is provider_error, moderation, timeout, canceled, insufficient_credits, invalid_input or unknown |
run.credits_estimated, run.credits_charged, run.credits_left | integer | null | See What a run cost |
run.started_at, run.finished_at | string | null | ISO 8601. finished_at is null while running |
next_action | string | Advice for agents. Don't branch on it |
partialmeans some steps delivered,failedmeans none did, andcanceledmeans a person canceled it in the app.- A
skippednode never ran because a step it needed failed. Nothing charged. waiting_approvalis in the status enum but never set. Don't branch on it.- A talking actor node runs its voice step, then the video. Both show under its
generations. The voice is a working file: itsasset_idandurlarenull. - A refused script shows at its step as
error.code: "moderation", not on the invoke. - An output
urlisnulluntil its generation iscompletedand its charge is final. It never expires: Download links.
What a run cost
| Field | Notes |
|---|---|
credits_estimated | The most the run was expected to cost, from when it started |
credits_charged | The whole run's cost, or null while the run is going. Never show null as 0 |
credits_left | Workspace credits after the run, when the read could look them up |
- A node has no cost of its own, and there is no running total: a number that is still growing is not a price.
- On
partial,credits_chargedis what the finished steps really cost. The failed ones charged nothing.
List runs
GET/api/v1/workflow-runsAPI key
GET/api/v1/workflows/{id}/runsAPI key
Newest first: every run in the workspace, or one workflow's. Same query, same response.
| Parameter | Type | Notes |
|---|---|---|
status | string | One value, or several separated by commas: queued, running, waiting_approval, completed, partial, failed, canceled |
source | string | Who started the run: ui, api, mcp, cli, workflow, agent, preset |
limit | integer | Default 25, max 50 |
cursor | string | The previous next_cursor, with the same filters |
curl -sG https://app.riffads.com/api/v1/workflow-runs \
-H "Authorization: Bearer $RIFFADS_API_KEY" \
--data-urlencode "status=completed,partial"The answer has ok, runs and next_cursor. Each row has workflow_run_id, workflow_id, workflow_name, template_key, status, still_running, source, step_count, steps_completed, steps_failed, steps_skipped, credits_charged, created_at, started_at and finished_at.
template_keyisnullfor a workflow that is not a template copy.steps_failedcounts failed and canceled steps together.credits_chargedis the run's cost,nulluntil the run is over.- Rows carry no link and no person's name. Files come from the run read.
- No
total: onlynext_cursor: nullis the end. The list rule. - A bad
statusorsourceis400 invalid_config, naming the accepted values. - An unknown workflow id is
404 not_found. A deleted workflow still lists its runs. - A run's generations always say
source: "workflow". To find agent workflow spend, filter runs here bysource.
Errors
A refused invoke charges nothing. Branch on code and retryable.
| Code | HTTP | Retryable | Cause |
|---|---|---|---|
insufficient_scope | 403 | no | Key lacks the Workflows scope |
not_found | 404 | no | Unknown template, workflow, run, actor or voice id, or another workspace's |
invalid_config | 400 | no | Bad body or input, a graph with nothing to run, or a bad list filter |
insufficient_credits | 402 | no | Not enough credits to start |
max_credits_exceeded | 402 | no | The run needs more than your max_credits. Carries limit |
spend_limit_exceeded | 402 | no | A workspace or key limit refused it. limit.bound_by names it |
submission_in_flight | 409 | yes | This workflow is already running, or this key has a generation running |
not_priced | 409 | no | A model in the graph has no price yet |
request_blocked | 429 | no | The same request failed too often. Carries blocked_reason |
rate_limited | 429 | yes | Over 20 invokes a minute on this key. Carries retry_after_seconds |
moderation_unavailable | 503 | yes | Content checks are down, so nothing can start |
All codes: Errors.
Not here
- No authoring, no workflow list, no graph read. Get a
workflow_idfrom an invoke, a person, or the run list. - No cancel and no retry. Both live in the app. On
partial, start a new run. - No
/waitand no stream. Poll, or register a webhook. - No per-run callback. A callback field is refused with
400. Webhooks are registered once per workspace. - No single node run.
- No
Idempotency-Keyheader. A retry after the first run ends starts, and charges, a second run.