REST API

Workflows

List templates, run one, read the run node by node, and list past runs.

Read as Markdown

Run 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

EndpointScopeLimit per keyWhat it does
GET /workflows/templatesRead120 a minuteTemplates you can run, with fillable node ids
POST /workflows/templates/{key}/invokeWorkflows20 a minuteRuns a template
POST /workflows/{id}/invokeWorkflows20 a minuteRuns a workflow your workspace owns
GET /workflow-runs/{id}Read120 a minuteOne run, node by node
GET /workflow-runsRead120 a minuteEvery run in this workspace, newest first
GET /workflows/{id}/runsRead120 a minuteOne 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 key

No params, no paging. Templates your plan can't run are left out.

Terminal
curl -s https://app.riffads.com/api/v1/workflows/templates \
  -H "Authorization: Bearer $RIFFADS_API_KEY"
Response: 200 (trimmed)
{
  "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 key

Same body, same response. The path names the graph. Save the body as body.json:

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:

Terminal
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
Response: 201
{
  "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_estimated is the most the run is expected to cost. What it really cost is credits_charged on the run, once it ends.
  • summary says the same in plain words, ready to show a person.

Read the run

GET/api/v1/workflow-runs/{id}API key

It never blocks. Read it about every 30 seconds until run.still_running is false.

Terminal
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.completed and workflow_run.failed.
  • The same jobs on MCP and the CLI: Same job, every surface.

Template fields

FieldTypeNotes
template_keystringThe {key} in the invoke path
name, description, categorystringThe last two can be null. Never branch on category
step_countintegerEvery node except canvas notes: the most steps that can run and charge
inputsarrayOne entry per text field, open setting, actor slot and voice slot you may set

Input slots

FieldWhat it is
nodeNode id to use in inputs. Use it exactly
labelNode name, for people
fieldField on that node to fill
field_labelField name as people see it. A text box shows as value
kindtext, setting, actor or voice
acceptsSettings only: the legal values, in words
max_lengthText only: the character limit
filledtrue 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

FieldTypeRequiredRules
max_creditsintegeryesAbove zero. The most the whole run may cost
inputsarraynoAt most 60 entries
inputs[].nodestringyesNode id from the template list or a run you read
inputs[].fieldstringyesField name on that node
inputs[].valuestring, number or booleanyesScalar 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 /estimates prices one config, not a graph.
  • max_credits caps all steps added up. Too low: 402 max_credits_exceeded, nothing starts, and limit.required_credits says what the run needs.
  • Don't reuse credits_estimated as max_credits. It is usually lower than the total max_credits is 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 values accepts lists.
  • An actor slot takes an act_ id from GET /actors, a voice slot a voc_ id from GET /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 on f_video is matched to the face it invents. Send a voice only 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 value accepts does 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_id is 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

Response: 200 (trimmed)
{
  "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.

FieldTypeNotes
run.statusstringqueued, running, completed, partial, failed, canceled
run.still_runningbooleanfalse for the last four. Poll on this
run.summarystringWhere the run stands, in plain words. Show it as it is
run.nodes[].node_idstringThe same id inputs uses
run.nodes[].statusstringpending, ready, dispatching, running, completed, failed, skipped, canceled
run.nodes[].generationsarrayThe node's generations, each file with its url. Empty until the node runs
run.nodes[].textstring | nullA writer node returns text, no file
run.nodes[].errorobject | nullAn 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_leftinteger | nullSee What a run cost
run.started_at, run.finished_atstring | nullISO 8601. finished_at is null while running
next_actionstringAdvice for agents. Don't branch on it
  • partial means some steps delivered, failed means none did, and canceled means a person canceled it in the app.
  • A skipped node never ran because a step it needed failed. Nothing charged.
  • waiting_approval is 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: its asset_id and url are null.
  • A refused script shows at its step as error.code: "moderation", not on the invoke.
  • An output url is null until its generation is completed and its charge is final. It never expires: Download links.

What a run cost

FieldNotes
credits_estimatedThe most the run was expected to cost, from when it started
credits_chargedThe whole run's cost, or null while the run is going. Never show null as 0
credits_leftWorkspace 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_charged is 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.

ParameterTypeNotes
statusstringOne value, or several separated by commas: queued, running, waiting_approval, completed, partial, failed, canceled
sourcestringWho started the run: ui, api, mcp, cli, workflow, agent, preset
limitintegerDefault 25, max 50
cursorstringThe previous next_cursor, with the same filters
Terminal
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_key is null for a workflow that is not a template copy.
  • steps_failed counts failed and canceled steps together.
  • credits_charged is the run's cost, null until the run is over.
  • Rows carry no link and no person's name. Files come from the run read.
  • No total: only next_cursor: null is the end. The list rule.
  • A bad status or source is 400 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 by source.

Errors

A refused invoke charges nothing. Branch on code and retryable.

CodeHTTPRetryableCause
insufficient_scope403noKey lacks the Workflows scope
not_found404noUnknown template, workflow, run, actor or voice id, or another workspace's
invalid_config400noBad body or input, a graph with nothing to run, or a bad list filter
insufficient_credits402noNot enough credits to start
max_credits_exceeded402noThe run needs more than your max_credits. Carries limit
spend_limit_exceeded402noA workspace or key limit refused it. limit.bound_by names it
submission_in_flight409yesThis workflow is already running, or this key has a generation running
not_priced409noA model in the graph has no price yet
request_blocked429noThe same request failed too often. Carries blocked_reason
rate_limited429yesOver 20 invokes a minute on this key. Carries retry_after_seconds
moderation_unavailable503yesContent checks are down, so nothing can start

All codes: Errors.

Not here

  • No authoring, no workflow list, no graph read. Get a workflow_id from 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 /wait and 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-Key header. A retry after the first run ends starts, and charges, a second run.

On this page