Cascades Docs
Sign in to run requests with your own sandbox key. Sign in
View as Markdown Open in Claude Open in ChatGPT Add MCP server OpenAPI JSON OpenAPI YAML

Trigger a workflow

POST /api/v1/workflows/{id}/trigger
executions:write Idempotent Async MCP: cascades_trigger_workflow

Starts an execution and returns 202 immediately; the run proceeds asynchronously. Poll getExecution until status is terminal (completed, failed, cancelled, skipped) or awaiting_review, or subscribe to execution.completed / execution.failed.

Test vs live. execution_mode defaults to test, which uses synthetic vendor data and never bills — and works on drafts (active: false), so you can exercise a cascade before activating it. live requires an account with production access (403 live_mode_forbidden otherwise) and an active cascade (409 workflow_inactive otherwise).

Idempotency. Idempotency-Key is required (422 missing_idempotency_key if absent). Race-safe under concurrent identical submissions: the loser receives the same execution as the winner. A reused key with a different body returns 409 idempotency_conflict. Requires executions:write.

Asynchronous: the response is 202 Accepted. Poll GET /executions/{id} until status is terminal.

Path parameters

NameTypeDescription
idrequired integer

Workflow id. Only workflows owned by the token's account resolve; a foreign or deleted id returns 404.

Header parameters

NameTypeDescription
Idempotency-Keyrequired string

Unique per-business-event key. Identical resubmissions return the original response; conflicting bodies return 409 idempotency_conflict. Concurrent identical requests are race-safe. A missing or blank header returns 422 missing_idempotency_key.

The header is accepted up to 200 characters, but the stored key is namespaced to your client (api_client:<id>:<key>, and for re-evaluations api_client:<id>:reeval:<execution_id>:<key>) and the stored value is capped at 200 characters — so the effective limit on trigger is about 185 characters and lower still on re_evaluations. Use a UUID (36 characters) or another key of at most 128 characters to stay clear of the cap.

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Request body

application/json · TriggerRequest

The applicant payload and the execution mode for this run.

  • payload object The decision input. Put the subject under `applicant`; arbitrary nested fields are allowed and become the execution's `input_context`. Defaults to `{}` when omitted.
    • applicant ApplicantPayload Free-form applicant data forwarded to the workflow's first node as `context.applicant`. Field names depend on the workflow definition.
    • property object Optional property / tenancy details (as returned by `listWorkflowTestCases`).
  • execution_mode string `test` uses synthetic vendor data and never bills; `live` requires production access and an active cascade. One of test live
  • external_reference string Your correlation id for this run. Echoed on the execution and on every webhook event.
Example request
{
  "payload": {
    "applicant": {
      "first_name": "Jordan",
      "last_name": "Lee",
      "email": "jordan@example.com"
    }
  },
  "execution_mode": "test",
  "external_reference": "rv-app-20491"
}

Responses

  • 202 Execution accepted application/json

    Schema: TriggerResponse

    • data ExecutionSummary The shape returned by `triggerWorkflow`. Compared with `Execution` it carries `execution_mode` and never `assigned_to_user_id`.

      Schema: ExecutionSummary

      • id integer required
      • object string required
      • workflow_id integer required
      • status string required Lifecycle of an execution. `queued` (batch rows not yet dispatched), `pending`, `running` and `waiting` (paused on a Wait node or adverse-action waiting period) are in flight; `awaiting_review` is paused on human review; `completed`, `failed`, `cancelled` and `skipped` are terminal. One of queued pending running waiting awaiting_review completed failed cancelled skipped
      • execution_mode string One of test live
      • execution_key string, nullable The namespaced idempotency key (`api_client:<id>:<Idempotency-Key>`).
      • external_reference string, nullable
      • needs_human_review boolean required
      • review_status string required One of none in_review approved denied
      • started_at string (date-time), nullable
      • completed_at string (date-time), nullable
      • created_at string (date-time) required
      • updated_at string (date-time), nullable
    • meta Meta

      Schema: Meta

      • request_id string required Correlation id for this request. Also sent as the `X-Request-Id` response header; quote it when contacting support.
    202 example
    {
  "data": {
    "id": 1842,
    "object": "execution",
    "workflow_id": 27,
    "status": "pending",
    "execution_mode": "test",
    "execution_key": "api_client:12:3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "external_reference": "rv-app-20491",
    "needs_human_review": false,
    "review_status": "none",
    "started_at": null,
    "completed_at": null,
    "created_at": "2026-09-09T14:00:00Z",
    "updated_at": "2026-09-09T14:00:00Z"
  },
  "meta": {
    "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f"
  }
}
  • 400 malformed_body application/json

    Schema: ErrorEnvelope

    400 example
    {
  "error": {
    "code": "validation_failed",
    "message": "The request could not be processed.",
    "details": [
      {
        "field": "execution_mode",
        "message": "must be test or live"
      }
    ],
    "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f",
    "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/validation_failed"
  }
}
  • 401 Missing, malformed, expired or revoked bearer token. The WWW-Authenticate header carries the RFC 6750 challenge. application/json

    Schema: ErrorEnvelope

    401 example
    {
  "error": {
    "code": "unauthorized",
    "message": "A valid bearer token is required.",
    "details": [],
    "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f",
    "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/unauthorized"
  }
}
  • 403 insufficient_scope or live_mode_forbidden application/json

    Schema: ErrorEnvelope

    403 example
    {
  "error": {
    "code": "live_mode_forbidden",
    "message": "Live mode requires production access.",
    "details": [
      {
        "field": "execution_mode",
        "message": "live mode requires production access"
      }
    ],
    "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f",
    "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/live_mode_forbidden"
  }
}
  • 404 Resource does not exist or belongs to another tenant / api_client application/json

    Schema: ErrorEnvelope

    404 example
    {
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "details": [],
    "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f",
    "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/not_found"
  }
}
  • 409 idempotency_conflict or workflow_inactive (live trigger on a draft) application/json

    Schema: ErrorEnvelope

    409 example
    {
  "error": {
    "code": "idempotency_conflict",
    "message": "The Idempotency-Key has already been used with a different request payload.",
    "details": [],
    "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f",
    "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/idempotency_conflict"
  }
}
  • 422 missing_idempotency_key or validation_failed application/json

    Schema: ErrorEnvelope

    422 example
    {
  "error": {
    "code": "missing_idempotency_key",
    "message": "Idempotency-Key header is required.",
    "details": [],
    "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f",
    "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/missing_idempotency_key"
  }
}
  • 429 Rate limit exceeded (60 req/min per IP on /api/v1, 600 req/hour per token prefix, or 300 req/5 min per IP globally). The body is the standard error envelope and Retry-After gives the seconds until the window resets. application/json

    Schema: ErrorEnvelope

    429 example
    {
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry later.",
    "details": [],
    "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f",
    "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/rate_limited"
  }
}
  • Executions — The lifecycle of a run — every status, what terminal means, how to poll, cancel and re-evaluate, and where the report PDFs live.
  • Idempotency — Which endpoints require an Idempotency-Key, how the key is scoped, what happens on replay and on conflict, and how to choose good keys.
  • Sandbox vs live — What test mode does, what live mode requires, and exactly which requests are refused until your account is approved for production.
  • Your first screening — Step by step from a fresh sandbox key to a decided execution — trigger a test subject, pick the mock outcome, poll, handle review, and read the notice.
  • Quickstart — Mint a sandbox key, trigger your first cascade and read the decision in under five minutes — with curl, Node, Python, Ruby or an MCP agent.
Was this page helpful?
Last updated

Markdown version · OpenAPI