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

Run and wait for the result

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

stream: true

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.

Trigger by webhook

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.

support@sentientone.ai