API reference

Recommended integration order

1. POST /webhook_subscriptions — subscribe your endpoint to lifecycle events. Store the signing_secret from the response; it is shown exactly once.
2. POST /workflows/:id/trigger — start a run with a unique Idempotency-Key and your external_reference.
3. GET /executions/:id — poll until status leaves pending / running / waiting. Cascades is asynchronous; trigger returns 202 Accepted, not the final state.
4. Receive signed events at your subscriber URL: adverse_action.* (triggered / completed / failed / retry_scheduled) and execution.* (completed / failed). Verify X-Cascades-Signature before trusting the payload.
5. (If the workflow includes Human Review) POST /executions/:id/review_decisions to approve or deny a paused execution.

Authentication

Every request requires a bearer token. Click Authorize above and paste your token. Tokens are issued per ApiClient and carry a scope vocabulary: workflows:read, workflows:write, workflow_templates:read, executions:read, executions:read:full, executions:write, webhooks:read, webhooks:write. Each operation below lists the scope it enforces; a token without it receives 403 insufficient_scope. See /docs/concepts/scopes-and-keys.

Errors

Every non-2xx response is a JSON envelope: { "error": { "code", "message", "details": [], "request_id", "doc_url" } }. code is a stable machine-readable string; doc_url links to the reference page for that code at /docs/api/errors/<code>.

Rate limits

• 60 req/min per source IP on /api/v1/*
• 600 req/hour per token prefix (first 8 chars of bearer)
• 300 req/5min per IP globally

A throttled request receives 429 with the standard JSON error envelope (code: rate_limited) and a Retry-After header giving the number of seconds until the window resets. Honour Retry-After; when it is absent back off exponentially with a minimum 1-second wait.

Rate-limited responses (429) carry the JSON error envelope and a Retry-After header; see Keys, scopes and rate limits. Every error code is catalogued under Errors, and the events you receive are under Webhook events.