Start a run of this workflow

Creates a run and hands it to a worker. This returns 202 Accepted — the run has been ACCEPTED, not finished. Nothing has executed when you get the response: the run comes back with status: "pending" and no finishedAt, no durationMs, no steps. Take data.id — that is the run id — and then either poll GET /api/runs/{id} or subscribe to GET /api/runs/{id}/stream (SSE) for progress. Step output lands at steps[].outputData, keyed by steps[].nodeId (the step's stable name), on the run detail.

The request BODY is the trigger payload. Whatever JSON object you POST is handed to the flow as its trigger data and reshaped to look like a real delivery from that trigger's kind, so a webhook flow reads it as {{trigger.body.…}}, gains {{trigger.headers}}/{{trigger.query}}/{{trigger.method}}, and a schedule flow gets a schedule-shaped payload. The body is optional; an empty/absent body runs with an empty payload. To bypass reshaping and supply trigger data ALREADY in delivery shape (replaying a past run's exact triggerData, or a saved test payload), include "__shaped": true at the top level — that key is stripped and the rest is passed through verbatim.

That is exactly why environment is a QUERY parameter and not a body field. The body belongs to the caller; a top-level environment key in it would collide with the caller's own payload, and a __shaped replay carrying that key would both lose the key and silently flip the run's environment.

environment

• production — executes the PUBLISHED snapshot (latestVersionId), records triggerType: "api", obeys the workflow's concurrencyLimit, and appears in GET /api/runs by default. Publishing is required first: if the workflow is not active, or has no published version, the call is 409 CONFLICT with the message "Publish this workflow before running it in production". If the published version exists but cannot be loaded, it is also 409 ("…could not be loaded — republish it") rather than silently falling back to the draft.
• test — executes the live DRAFT, records triggerType: "manual", ignores the concurrency limit (so the editor stays responsive), and is filtered out of the default GET /api/runs.
• Omitted — resolves to production when the workflow is active AND has no unpublished changes; otherwise test. Passing fromNode or versionId forces the default to test, because both are rehearsals by construction.
• Any other value is a 400.

fromNode / versionId / retryOf

• fromNode — a PARTIAL run: execution starts at that step, with upstream values seeded from earlier test data rather than executed. It must name a step on the TOP-LEVEL chain (not inside a branch arm or loop body) — an interior or unknown name is 422. It is test-only: combined with environment=production it is a 400. The run records it as startedFromStep.
• versionId — replays a specific published snapshot instead of the draft ("retry as it ran"). The version must belong to THIS workflow or it is 404. Under environment=production it must be omitted or equal latestVersionId; anything else is 400, because a production run always executes the published version.
• retryOf — records lineage: this run is a retry of that run. The referenced run must belong to THIS workflow or it is 404. It changes nothing about what executes — pass versionId, fromNode and the original triggerData yourself to actually reproduce a run.

The definition is parsed and every piece it names is checked against what the live worker fleet can run BEFORE a run row is created, so an unrunnable flow is 422 and leaves no pending run behind.

Pass ?wait= to receive the finished run in this same call rather than a run id to poll.