API reference
Workflows API
Start live runs of published workflows with POST /v1/workflows/run or a webhook, read step events, and handle run errors.
Reference2 min readUpdated 23 October 2026
A published workflow can be started two ways: from your code with your secret key, or from any system that can send a webhook, with the workflow's own trigger token. Both start a live run of the published version. Test runs only start from the designer.
POST /v1/workflows/run
| Field | Notes |
|---|---|
workflow_id | The workflow to run |
input | An object with the Start step's fields. A mismatch fails with 400 INVALID_INPUT |
mode | "live" (default). "test" is refused with 403 TEST_RUN_NOT_ALLOWED |
stream | true (default) streams each step; false waits and returns the finished run as JSON |
curl https://api.sentientone.ai/v1/workflows/run \ -H "Content-Type: application/json" \ -H "X-Api-Key: $SENTIENTONE_API_KEY" \ -d '{"workflow_id": "…", "mode": "live", "stream": false, "input": {"email": "sam@example.com", "message": "My invoice is wrong"}}'Streamed events
data: {"type": "run", "run_id": "…"}data: {"type": "step", "step": {"node_id": "classify_1", "type": "classify", "label": "Classify", "status": "succeeded", "input": "…", "output": "billing", "error": null, "started_at": "…", "finished_at": "…", "duration_ms": 812, "tokens": 211}}data: {"type": "done", "run_id": "…", "status": "succeeded", "output": {…}, "error": null, "total_tokens": 1402}| type | Fields |
|---|---|
run | run_id, always first |
step | step: node_id, type, label, status, input, output, error, started_at, finished_at, duration_ms, tokens |
done | run_id, status (succeeded or failed), output, error, total_tokens, and error_code and request_id on failure |
error | code: "INTERNAL_ERROR", run_id, message, request_id, if the run itself crashed |
With "stream": false the response body is the done payload without type. Both modes return X-Trace-Id and X-Workflow-Run-Id headers.
Webhook trigger
Every published workflow has a hook URL on the app and a trigger token (wft_…, shown once; only its hash is stored). Send the token as X-Workflow-Token or ?token=. The JSON body (up to 100 KB) becomes the run's input.
curl -X POST "https://app.sentientone.ai/api/workflows/hooks/$WORKFLOW_ID?wait=true" \ -H "Content-Type: application/json" \ -H "X-Workflow-Token: $WORKFLOW_TOKEN" \ -d '{"email": "sam@example.com", "message": "My invoice is wrong"}'| Response | When |
|---|---|
202 {"run_id", "status": "queued"} | Default: the run starts and you get its id straight away |
200 {"run_id", "status", "output", "error"} | ?wait=true and the run finishes within 30 seconds |
202 {"run_id", "status": "running"} | ?wait=true but the run is still going after 30 seconds |
400 | The body isn't a JSON object, or it doesn't match the Start step's fields |
401 | The workflow id or token is wrong |
409 | The workflow isn't published (WORKFLOW_NOT_PUBLISHED) |
413 | The body is larger than 100 KB |
429 | More than 60 triggers a minute for this workflow |
Webhook errors use a flat {"error": "…"} body. Rotating the trigger token in the designer stops the old token at once.
Limits and credits
30 runs a minute and 5 at once per account; a run has 280 seconds and at most 25 steps. A live run that contains an HTTP, Webhook, Slack or Email block costs 1 credit when it starts; Agent, Classify, Extract and AI-judged Guardrail steps cost 1 credit each. Full detail: Workflow limits.
Still stuck?
Email us with what you tried and any request id. A person replies.