Run workflow
Runs a workflow version. ?version=active (default), draft, or v{n}. Body: { input, groupId?, groupName?, runtimeAuth? } — input is the workflow input, groupId/groupName select the group the run is attributed to (like /v1/chat), and runtimeAuth supplies per-request credentials for tool steps (custom + MCP). Drafts are validated at run time and rejected with 422 if invalid. The run executes as an end user: call it with that user’s session token. Pass stream: true to receive Server-Sent Events instead of a single JSON body: each workflow stream event is emitted as a data: line, and the stream ends with a run-complete event carrying the same payload as the non-streaming response (run-error on failure). Pre-run errors (400/404/422) are returned as plain JSON either way.
Authorizations
Session token (snat_…) minted by POST /v1/token. Carries the organization and the end user; safe in a browser.
Path Parameters
"4c2f9e18-7a63-4d05-b1e8-93a7c0f2d641"
Query Parameters
active (default) | draft | v{n}
Body
The workflow input: an object whose keys are the fields the version's input_schema declares (validated against that schema by the run). Omit it to run with {}.
Optional stable caller-supplied group id. When sent, group matching is by this id; a differing groupName renames the group.
1 - 255"grp_84f20c19"
Optional group name. Without groupId this matches by name; alongside groupId it is display-only (rename on change).
"Acme — production"
Runtime authentication map: { [providerNameOrId]: { credentials } } — used by tool steps (custom + MCP)
When true, respond with Server-Sent Events: one data: line per workflow stream event (step start/output/result, nested agent events, …), ending with a run-complete (or run-error) event that carries the same payload as the non-streaming JSON response.
false
When true (active version only), the run also files its result as a new conversation in the user's thread list — exactly like a scheduled run: pre-titled, marked unread, with the inputs, the output and the run's text output. The response then carries run_id and thread_id; stream is ignored. Use it to trigger a workflow from your own UI without a chat turn.
false
With notify_thread: the conversation title (default " — ").
1 - 200"Refund triage — 21 Aug"
Response
Run completed (JSON), or — with stream: true — a text/event-stream of workflow events ending in run-complete/run-error. The run-complete event carries exactly the JSON body documented here.
completed. A failed run answers 500 with {error, details}.
Which environment the run was attributed to.
The version number that ran — 0 when you ran the draft.
Correlates this run with its observability trace. Also returned as the X-Request-Id / X-Trace-Id response headers.
The workflow's own output, shaped by the version's output_schema — so this varies per workflow. Steps that produce no output leave it empty.
With notify_thread: the workflow_runs row.
With notify_thread: the conversation the result was filed in.
The run's text output. With notify_thread: the text posted to the thread — the workflow's output_text rendered against this run, else a completion notice with the output attached. Without it: the rendered output_text, or null when the version declares none.