Runs

Start workflow runs (SSE) and single-node runs; retrieve a run's persisted outputs.

Run a workflow

POST /v1/runs

Runs a workflow and streams run events back as Server-Sent Events.

Request body

Field	Type	Description
`workflow`	object	Inline workflow definition — for one-off runs
`workflowRef`	string	`<id>@<version>` reference to a published workflow — the id is the published `<org-slug>/<workflow-slug>` address (preferred, e.g. `acme/sprite-pack@2.1.0`) or the workflow's UUID (e.g. `8f61e451-…@2.1.0`); omit the version or use `@latest` for the current one
`inputs`	object	Run inputs — Artifacts keyed by the workflow's input names
`maxCostUsd`	number	Spend cap for this run, in USD. Defaults to $0.50 when omitted; the server caps requests at its $1.00 per-run ceiling

Provide exactly one of workflow or workflowRef — both or neither is a 400.

Response: SSE stream

Content-Type: text/event-stream. Each event is a data: line of JSON; the stream ends with data: [DONE]:

curl -N -X POST "https://studio.blitflow.com/api/v1/runs" \
  -H "Authorization: Bearer $BLITFLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workflowRef": "acme/sprite-pack@latest", "inputs": {"prompt": {"kind": "text", "value": "isometric stone tower"}}, "maxCostUsd": 0.25}'

data: {"type":"step.started","nodeId":"gen"}

data: {"type":"step.completed","nodeId":"gen","usage":{"costUsd":0.012,"ms":4183}}

data: {"type":"run.completed","outputs":{"image":{"kind":"image","ref":"https://…/out.png","mimeType":"image/png"}}}

data: [DONE]

Keep the connection open (curl -N) and read to the terminal event: run.completed carries the outputs; run.failed carries { error: { code, message } }. Failures after the stream starts arrive as events, not HTTP status codes.

Errors (before the stream starts)

Status	Cause
`400`	Invalid JSON, schema violation, bad `workflowRef`, or not exactly one of `workflow`/`workflowRef`
`401`	Bad token
`404`	`workflowRef` doesn't resolve to a published version

Get a run (with its outputs)

GET /v1/runs/:id

Fetches one run by id: status, per-node steps (duration, cost, exact error for failed nodes), and — for completed runs — outputs, the same name → Artifact record the run.completed event carried. Outputs are persisted at completion, so a caller who lost the SSE stream (or polls later) can still retrieve exactly what the run produced. Run ids come from the run.started event, or from GET /v1/runs (run history).

{
  "id": "8f61e451-…",
  "status": "completed",
  "steps": [{ "nodeId": "gen", "status": "completed", "costUsd": 0.012 }],
  "outputs": {
    "image": { "kind": "image", "ref": "https://…/out.png" }
  }
}

outputs is null while the run is pending/running and for failed runs. Output refs are Blitflow-hosted blob URLs; after the artifact retention window a ref's blob may no longer resolve even though the envelope is still recorded.

Run a single node

POST /v1/runs/node

Executes one node by id — no workflow graph needed. Ideal for one-off inference. Supports model and llm nodes; use POST /v1/runs for graphs.

Request body

Field	Type	Description
`node`	string	Node id, e.g. `rd-fast`
`inputs`	object	Keyed by the node's input port names. Scalars (`string`, `number`, `boolean`, `null`) for value ports; Artifacts for data ports
`maxCostUsd`	number	Spend cap in USD

Response

A single JSON body (no stream):

{
  "outputs": {
    "image": {
      "kind": "image",
      "ref": "https://…/key.png",
      "mimeType": "image/png"
    }
  }
}

runs.node is currently served through the MCP tools and the SDK's in-process clients. Over plain HTTP, wrap the node in a minimal one-node workflow and use POST /v1/runs.

Example (SDK)

const { outputs } = await client.ops["runs.node"]({
  node: "rd-fast",
  inputs: { prompt: "a brass key", removeBg: true, seed: 7 },
  maxCostUsd: 0.1,
});

On this page