POST/api/v1/flows/{flowId}/runs
Spawns a fresh sandboxed Claude-CLI container running this flow. If
prompt is provided, it’s sent as the initial message; otherwise the
flow’s pre-configured prompt (if any) is used.
Pass Idempotency-Key header (or idempotencyKey in the body) to
deduplicate retries within 24 hours.
Authentication
Requires a project API key — see Authentication.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
flowId | path | string | required | UUID of the flow to trigger. |
Idempotency-Key | header | string | optional | Deduplicate retries within 24 hours for this project. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
prompt | string | optional | Initial message sent to the agent. |
idempotencyKey | string | optional | |
callbackUrl | string uri | optional | HTTPS URL to receive the signed run.finished webhook. |
Responses
| Status | Description |
|---|---|
200 | Idempotency hit — existing run returned. |
201 | Run created. |
400 | Request body or query parameters failed validation. |
401 | Missing, malformed, expired, or revoked API key. |
403 | Flow does not belong to this project. |
404 | Resource not found or not accessible to this project. |
409 | Self-hosted runner is offline. |
429 | Rate limit, concurrent cap, or monthly quota exceeded. |
Tag: Runs