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. Its runId is the same id as run_id below.

run_id
string<uuid> | null

The run's row in the run log: GET /v1/workflow-runs/{run_id} returns its status, output, text and request id. Present on every response — success or failure, any version, streaming (run-complete / run-error) or not — and real as soon as the response arrives (the row is opened before the run starts). The same value as result.runId. Null only when the run log could not be written.

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.