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.

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 1
Option 2
definition object REQUIRED
Definition is the full workflow graph to execute. Must contain a "root" node with type "manual". All action nodes referenced in children arrays must be present.
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
Array of:
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"}
Previous GET /v1/runs
Next GET /v1/runs/{id}