Skip to main content
POST
Run workflow

Authorizations

Authorization
string
header
required

Session token (snat_…) minted by POST /v1/token. Carries the organization and the end user; safe in a browser.

Path Parameters

id
string
required
Example:

"4c2f9e18-7a63-4d05-b1e8-93a7c0f2d641"

Query Parameters

version
string
default:active

active (default) | draft | v{n}

Body

application/json
input
object

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 {}.

Example:
groupId
string | null

Optional stable caller-supplied group id. When sent, group matching is by this id; a differing groupName renames the group.

Required string length: 1 - 255
Example:

"grp_84f20c19"

groupName
string | null

Optional group name. Without groupId this matches by name; alongside groupId it is display-only (rename on change).

Example:

"Acme — production"

runtimeAuth
object

Runtime authentication map: { [providerNameOrId]: { credentials } } — used by tool steps (custom + MCP)

Example:
stream
boolean
default:false

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.

Example:

false

notify_thread
boolean
default: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.

Example:

false

thread_title
string

With notify_thread: the conversation title (default "").

Required string length: 1 - 200
Example:

"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.

status
string

completed. A failed run answers 500 with {error, details}.

environment
string

Which environment the run was attributed to.

version
integer

The version number that ran — 0 when you ran the draft.

traceId
string

Correlates this run with its observability trace. Also returned as the X-Request-Id / X-Trace-Id response headers.

result
object

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.

run_id
string<uuid>

With notify_thread: the workflow_runs row.

thread_id
string

With notify_thread: the conversation the result was filed in.

text
string | null

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.