POST /v1/runs
Execute an inline workflow definition (ephemeral run). The definition must use "manual" trigger type. No workflow is saved — the definition is executed once and the run is recorded with workflowId="". Requires WorkflowCreate permission.

Request Body required

Inline workflow definition and optional payload/props
application/json
One of:
Option 1object
Option 2
definition object REQUIRED
Definition is the inline workflow graph to analyze. Same shape as a saved workflow's definition. Unlike the ephemeral-run endpoint there is no trigger restriction — analysis is read-only and method-agnostic.
blockExpansions object
Set on run snapshots only (not workflow DB)
inputSchema object[]
Array of:
description string
key string
required boolean
type string
"string", "number", "boolean", "object", "array"
nodes object REQUIRED
sensitivePropKeys string[]
Legacy: kept for old runs; no longer populated for new workflows
triggerNodeIds string[]

TriggerNodeIDs lists the node IDs that are trigger (root) nodes. Every workflow declares this — single-trigger workflows ship ["root"] (the legacy node id), multi-trigger workflows list every trigger node id. Treating single-trigger as a forest-of-1 removes the two-path branching throughout the BE + FE; older rows without the field are backfilled by migration 000282 and the field-missing path stays as a read-side safety net (see FindTriggerNodeIDs) but is no longer exercised by saves.

"root" is also a runtime alias for "the trigger that fired this run" — {{root.X}} variable references resolve to the firing trigger regardless of which trigger fired. Don't repurpose the literal "root" as a trigger id on a multi-trigger workflow.

variableDefs object[]
VariableDefs is a snapshot of the workflow's declared variables at run creation time. The canonical source lives on the workflows row (Workflow.VariableDefs column). Snapshotted into the run definition so the worker can resolve {{$vars.x}} lookups and route variable-action writes to the right scope without an extra DB round trip.
Array of:
default unknown
description string
lifetime string
Values persist reset
name string
type string
Values number text boolean list object
payload object
Payload is merged into the trigger result (root node output), accessible via {{root.result.key}} expressions. A "triggeredAt" timestamp is always added automatically.
propValues object
PropValues are template parameter values injected into the run context, accessible via {{$props.key}} expressions.
runId string
RunID is an optional client-generated run ID. Must start with "run_" prefix. If omitted, a run ID is generated server-side. Use this to subscribe to SSE stream before triggering the run.

Responses

200 Run created and enqueued for execution
application/json
code integer
data object
runId string
message string
requestId string
400 Invalid definition (400228), non-manual trigger (400229), invalid run ID (400078), or duplicate run ID (400079)
402 Insufficient CU balance
403 Missing org context or insufficient permissions
curl -X POST 'https://api.example.com/v1/runs' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{}'
const response = await fetch('https://api.example.com/v1/runs', {  method: 'POST',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({})});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://api.example.com/v1/runs', headers=headers, json={})print(response.json())
package mainimport (	"fmt"	"io"	"net/http"	"strings")func main() {	body := strings.NewReader(`{}`)	req, _ := http.NewRequest("POST", "https://api.example.com/v1/runs", body)	req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")	req.Header.Set("Content-Type", "application/json")	resp, _ := http.DefaultClient.Do(req)	defer resp.Body.Close()	result, _ := io.ReadAll(resp.Body)	fmt.Println(string(result))}
200 Response
{  "code": 200,  "data": {    "runId": "run_c9i6j8k2l0m3"  },  "message": "success",  "requestId": "abc-123"}
Ask a question... ⌘I