Workflows API

Run a saved workflow or a published template from code, then read it node by node until it ends. What a workflow is: workflows guide.

The four routes

• Every key has Read.
• Invokes need the Workflows scope, set when the key is created. generate alone can't start a run. Without it: 403 insufficient_scope. Authentication.

The loop

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",
      "description": "A creator you invent, talking straight to camera about your brand",
      "category": "End to end",
      "step_count": 7,
      "inputs": [
        {
          "node": "f_brand",
          "label": "Brand context",
          "field": "text",
          "field_label": "value",
          "kind": "text",
          "max_length": 8000,
          "filled": true
        }
      ]
    }
  ]
}

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 '{
    "max_credits": 1200,
    "inputs": [
      { "node": "f_brand", "field": "text", "value": "Lumen Skin, direct to consumer skincare..." }
    ]
  }'

{
  "ok": true,
  "workflow_run_id": "wfr_0193c8f0a1b24e7f9d3c5a6b7e8f0077",
  "workflow_id": "wf_0193c8f0a1b24e7f9d3c5a6b7e8f0055",
  "template_key": "ugc_face_cam",
  "billable_node_count": 6,
  "applied_inputs": [{ "node": "f_brand", "field": "text" }],
  "replay": false,
  "credits": {
    "credits_estimated": 742,
    "credits_charged_so_far": 0,
    "credits_charged": null,
    "settlement": "open",
    "terminal": false,
    "wallet_balance": 8321
  },
  "next_action": "This run has 6 steps to work through and takes minutes, not seconds. It is accepted, not finished. GET /api/v1/workflow-runs/wfr_0193c8f0a1b24e7f9d3c5a6b7e8f0077 about every thirty seconds until still_running is false. Do not tell the person it is ready until then, and do not hand the checking back to them."
}

curl -s https://app.riffads.com/api/v1/workflow-runs/wfr_0193c8f0a1b24e7f9d3c5a6b7e8f0077 \
  -H "Authorization: Bearer $RIFFADS_API_KEY"

• MCP: list_templates, run_workflow and get_workflow_run. MCP tools.
• CLI: riffads workflows templates and riffads workflows invoke --template <key>. Commands.

Template fields

Input slots

Invoke body

{
  inputs?: Array<{ node: string; field: string; value: string | number | boolean }>;
  max_credits: number;
}

Strict at both levels. An unknown key is 400 invalid_config.

Sizing max_credits

• max_credits is checked against every step's estimate plus 10%, summed.
• There is no run estimate endpoint. POST /estimates prices one config, not a graph. Size from step_count and leave room.
• Too low: 402 max_credits_exceeded, with limit.bound_by: "max_credits". The message names both numbers. Nothing starts.

What inputs can set

• Inputs patch this run's snapshot only. The saved workflow never changes.
• All or nothing. One bad entry refuses the whole call. Nothing starts.
• A later entry for the same field wins.

Refused, each with a message that says why:

{
  "error": {
    "ok": false,
    "code": "invalid_config",
    "message": "This workflow has no node called \"brand\". Use a node id exactly as list_templates or get_workflow_run reported it. Nothing was started and nothing was charged.",
    "retryable": false,
    "credits_charged": 0
  }
}

Messages name MCP tools like list_templates. The REST route is GET /api/v1/workflows/templates.

Invoking by template key

• The first run creates your workspace's copy: one workflow per template, its name ending in (agent). Later runs of that key reuse it.
• The copy keeps the template's node ids, so the template's inputs list works on it.
• workflow_id in the response is that copy. Invoking it by 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. Same key again while it runs: 409 submission_in_flight, "This workflow is already running. Wait for it to finish." Different workflows can run at once, up to your plan's render limit.
• Unpublished and unknown keys 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,
    "nodes": [
      {
        "node_id": "f_analyze",
        "label": "Analyze the brand",
        "status": "completed",
        "credits": 2,
        "generations": [
          {
            "generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f0011",
            "capability_id": "script_llm",
            "status": "completed",
            "outputs": [],
            "credits": {
              "credits_held": 3,
              "credits_charged": 2,
              "settlement": "captured",
              "terminal": true
            }
          }
        ],
        "text": "Lumen Skin sells to people who read the ingredient list first...",
        "error": null
      },
      {
        "node_id": "f_video",
        "label": "The face cam",
        "status": "completed",
        "credits": 400,
        "generations": [
          {
            "generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033",
            "capability_id": "veo_31",
            "status": "completed",
            "outputs": [
              {
                "index": 0,
                "kind": "video",
                "url": "https://<signed-url>",
                "file_name": "veo-31-0.mp4",
                "width": 1080,
                "height": 1920
              }
            ],
            "credits": {
              "credits_held": 440,
              "credits_charged": 400,
              "settlement": "captured",
              "terminal": true
            }
          }
        ],
        "text": null,
        "error": null
      }
    ],
    "credits": {
      "credits_estimated": 742,
      "credits_charged_so_far": 402,
      "credits_charged": 402,
      "settlement": "captured",
      "terminal": true,
      "wallet_balance": 8133
    },
    "started_at": "2026-09-17T10:04:11.482Z",
    "finished_at": "2026-09-17T10:12:02.900Z"
  },
  "output_urls_expire_in_seconds": 600,
  "next_action": "This run is finished and credits_charged is final. The output links below expire in 10 minutes, so pass them on now."
}

Each generations entry has the same shape as GET /generations/{id}. Generations API.

• partial: some steps delivered. failed: none did.
• skipped: the node never ran because an input it needed failed. Nothing charged.
• canceled: a person canceled the run in the app.
• waiting_approval exists in the status enum but is never set. Don't branch on it.
• A talking actor node runs its own voice step, then the video. Both show under that node's generations.
• A refused script shows up at its step as error.code: "moderation", not on the invoke.

The credits object

credits_charged is null while the run is open. Never show it as 0.

What next_action says

Getting the files

• run.nodes[].generations[].outputs[].url is null until that generation is completed.
• Links last 600 seconds. Download now. Read the run again for fresh links. Results guide.

Errors

Standard error envelope. Branch on code and retryable, never the message.

Any refused invoke charges nothing. All codes: error codes.

Not here

• No authoring. No create, edit or delete.
• No workflow list, no graph read. Get a workflow_id from an invoke or from a person.
• No run list. Keep your workflow_run_id.
• No cancel, no retry. Both live in the app. On partial, start a new run.
• No /wait, no stream. Poll.
• No webhooks. The body is strict, so a callback field is a 400.
• No single node run. No scope or target_node_id.
• No Idempotency-Key header. A blind retry starts and charges a second run, unless the first is still running (409). replay: true is authoritative when present.