# Cascades API

> Cascades runs bureau-backed screening cascades (credit, criminal, eviction, identity) through one REST API: trigger a cascade for an applicant, poll the execution, receive webhooks, and draft adverse-action notices. Sandbox keys run against test identities; live runs need an approved account.

Every page below has a markdown twin at the same URL with a `.md` suffix (or `Accept: text/markdown`). The full corpus is at https://cascades.crscreditapi.com/llms-full.txt. The OpenAPI 3.0 document at https://cascades.crscreditapi.com/openapi.json is the source of truth for the reference pages, the code samples and the MCP tool manifest.

## Get started

- [Overview](https://cascades.crscreditapi.com/docs.md): Run tenant, employment and credit screening decisions through one REST API and MCP server. Start in the sandbox, go live when approved.
- [Quickstart](https://cascades.crscreditapi.com/docs/quickstart.md): 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.
- [Sandbox vs live](https://cascades.crscreditapi.com/docs/concepts/sandbox-vs-live.md): What test mode does, what live mode requires, and exactly which requests are refused until your account is approved for production.
- [Test identities](https://cascades.crscreditapi.com/docs/sandbox/test-identities.md): The synthetic applicants registered in the CRS sandbox, what test mode really does with them, and how to pick a mock outcome for a test run.

## Concepts

- [Cascades](https://cascades.crscreditapi.com/docs/concepts/cascades.md): What a cascade is, the node grammar behind the definition array, and how to list, create, update, activate and delete cascades through the API.
- [Executions](https://cascades.crscreditapi.com/docs/concepts/executions.md): The lifecycle of a run — every status, what terminal means, how to poll, cancel and re-evaluate, and where the report PDFs live.
- [Batches](https://cascades.crscreditapi.com/docs/concepts/batches.md): Run up to 500 applicants through one cascade in a single request, track per-row status, cancel, resume or retry, and export the results.
- [Human review](https://cascades.crscreditapi.com/docs/concepts/human-review.md): How a cascade pauses for a reviewer, what awaiting_review means for your integration, and the endpoints to claim, decide, note and audit reviews.
- [Adverse action](https://cascades.crscreditapi.com/docs/concepts/adverse-action.md): How an AdverseAction node fires, the notice stages and flows, the draft-first default, the webhook events it emits, and where the notice PDFs end up.
- [Webhooks](https://cascades.crscreditapi.com/docs/concepts/webhooks.md): Subscribe to execution and adverse-action events, verify the HMAC signature, handle retries idempotently, and rotate secrets without downtime.
- [Idempotency](https://cascades.crscreditapi.com/docs/concepts/idempotency.md): Which endpoints require an Idempotency-Key, how the key is scoped, what happens on replay and on conflict, and how to choose good keys.
- [Pagination and filtering](https://cascades.crscreditapi.com/docs/concepts/pagination-and-filtering.md): page and per_page, the meta block on every collection, filter[...] parameters including CSV values, and which lists are not paginated.
- [Keys, scopes and rate limits](https://cascades.crscreditapi.com/docs/concepts/scopes-and-keys.md): How API keys are issued and expire, what each scope grants, how tokens map to your data, the rate limits, and the 429 envelope.
- [Glossary](https://cascades.crscreditapi.com/docs/concepts/glossary.md): Definitions of the terms the Cascades API docs use — cascade, node, execution, step outputs, batch, decision, scope, idempotency key, webhook event.

## Guides

- [Your first screening](https://cascades.crscreditapi.com/docs/guides/first-screening.md): 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.
- [Verify webhook signatures](https://cascades.crscreditapi.com/docs/guides/verify-webhooks.md): Drop-in Ruby, Python and Node verifiers for X-Cascades-Signature, with timestamp tolerance, constant-time comparison and secret-rotation support.
- [Handle human review](https://cascades.crscreditapi.com/docs/guides/handle-human-review.md): Build a review queue on the API — find paused executions, claim them, approve or deny with a note, act in bulk, and reconcile with the audit trail.
- [Generate a cascade with AI](https://cascades.crscreditapi.com/docs/guides/ai-generate-a-cascade.md): Turn a plain-English screening policy into a valid cascade with POST /workflows/generate, preview before saving, and handle the busy and failure cases.

## API reference

- [API reference](https://cascades.crscreditapi.com/docs/api.md): Base URL, authentication, envelopes, rate limits and every endpoint
- [Error codes](https://cascades.crscreditapi.com/docs/api/errors.md): Every error code the API returns, with causes and fixes
- [Webhook events](https://cascades.crscreditapi.com/docs/api/webhooks.md): Signing scheme, retry schedule and every event payload
- [List workflows — GET /api/v1/workflows](https://cascades.crscreditapi.com/docs/api/workflows/list-workflows.md): Workflows owned by the account behind the token, newest first.
- [Create a workflow — POST /api/v1/workflows](https://cascades.crscreditapi.com/docs/api/workflows/create-workflow.md): Creates a cascade from a JSON definition (see CascadeDefinition for the node grammar), owned by the account behind the token.
- [Generate a workflow from a prompt — POST /api/v1/workflows/generate](https://cascades.crscreditapi.com/docs/api/workflows/generate-workflow.md): Builds a cascade definition from a plain-English policy description using the AI builder, validates it (with one automatic repair pass), and — by default — saves it as a new workflow exactly like c...
- [Show a workflow — GET /api/v1/workflows/{id}](https://cascades.crscreditapi.com/docs/api/workflows/get-workflow.md): Returns the workflow including its full definition.
- [Update a workflow — PATCH /api/v1/workflows/{id}](https://cascades.crscreditapi.com/docs/api/workflows/update-workflow.md): Partial update: only the keys present in the body change.
- [Delete a workflow — DELETE /api/v1/workflows/{id}](https://cascades.crscreditapi.com/docs/api/workflows/delete-workflow.md): Soft-deletes the cascade.
- [List sandbox test cases for a workflow — GET /api/v1/workflows/{id}/test_cases](https://cascades.crscreditapi.com/docs/api/workflows/list-workflow-test-cases.md): The synthetic subjects registered in the CRS Testcase Service for this cascade's product nodes (credit, criminal, eviction …).
- [Trigger a workflow — POST /api/v1/workflows/{id}/trigger](https://cascades.crscreditapi.com/docs/api/workflows/trigger-workflow.md): Starts an execution and returns 202 immediately; the run proceeds asynchronously.
- [List published templates — GET /api/v1/workflow_templates](https://cascades.crscreditapi.com/docs/api/workflow-templates/list-workflow-templates.md): Read-only catalog, ordered by name.
- [Show a template (with definition) — GET /api/v1/workflow_templates/{id}](https://cascades.crscreditapi.com/docs/api/workflow-templates/get-workflow-template.md): Returns the template including its definition, which you can pass to createWorkflow.
- [List executions — GET /api/v1/executions](https://cascades.crscreditapi.com/docs/api/executions/list-executions.md): Executions started by the calling api_client, newest first.
- [Show an execution — GET /api/v1/executions/{id}](https://cascades.crscreditapi.com/docs/api/executions/get-execution.md): Returns the detail view (Execution + input_context).
- [Cancel an execution — POST /api/v1/executions/{id}/cancel](https://cascades.crscreditapi.com/docs/api/executions/cancel-execution.md): Cancels a pending, running, or waiting execution, any outstanding waits, and any unresolved adverse-action drafts.
- [Re-evaluate an execution — POST /api/v1/executions/{id}/re_evaluations](https://cascades.crscreditapi.com/docs/api/executions/re-evaluate-execution.md): Creates a new execution that re-runs the source's input_context against the source's snapshotted definition (NOT the workflow's current definition) and returns 202; poll getExecution on the new id.
- [Approve or deny a paused review — POST /api/v1/executions/{id}/review_decisions](https://cascades.crscreditapi.com/docs/api/executions/submit-review-decision.md): Records the decision on an execution that is awaiting_review (or waiting) with needs_human_review: true, auto-claims it for the caller if unassigned, and resumes the chosen branch.
- [List review audit events — GET /api/v1/executions/{id}/review_events](https://cascades.crscreditapi.com/docs/api/executions/list-review-events.md): Returns flagged / assigned / unassigned / approved / denied / note_added / re_evaluated events, plus the adverse_action_drafted / adverse_action_sent / adverse_action_skipped / adverse_action_repla...
- [Claim or unassign a review — POST /api/v1/executions/{id}/review_assignment](https://cascades.crscreditapi.com/docs/api/executions/assign-review.md): assignee: "me" claims the review for the calling api_user; assignee: null releases it.
- [Append a review note — POST /api/v1/executions/{id}/review_notes](https://cascades.crscreditapi.com/docs/api/executions/add-review-note.md): Records a note_added audit event on the execution.
- [Bulk approve / deny / assign_to_me — POST /api/v1/executions/review_bulk_actions](https://cascades.crscreditapi.com/docs/api/executions/bulk-review-actions.md): Always asynchronous.
- [List credit-report PDFs for an execution — GET /api/v1/executions/{id}/report_artifacts](https://cascades.crscreditapi.com/docs/api/executions/list-report-artifacts.md): Metadata only; the whole list is returned in one response (not paginated — page / per_page are ignored).
- [Download a credit-report PDF — GET /api/v1/executions/{id}/report_artifacts/{artifact_id}](https://cascades.crscreditapi.com/docs/api/executions/get-report-artifact.md): Returns the binary PDF as an attachment.
- [List adverse-action notice PDFs for an execution — GET /api/v1/executions/{id}/notice_artifacts](https://cascades.crscreditapi.com/docs/api/executions/list-notice-artifacts.md): Metadata only; not paginated (page / per_page are ignored).
- [Download an adverse-action notice PDF — GET /api/v1/executions/{id}/notice_artifacts/{artifact_id}](https://cascades.crscreditapi.com/docs/api/executions/get-notice-artifact.md): Returns the binary PDF as an attachment.
- [Create a batch from N rows — POST /api/v1/workflows/{id}/batches](https://cascades.crscreditapi.com/docs/api/batches/create-batch.md): Pre-creates the batch and N queued child executions in a single transaction and returns 202; the rows are then processed asynchronously.
- [List batches — GET /api/v1/batches](https://cascades.crscreditapi.com/docs/api/batches/list-batches.md): Batches created by the calling api_client, newest first.
- [Show a batch — GET /api/v1/batches/{id}](https://cascades.crscreditapi.com/docs/api/batches/get-batch.md): Batch status and counters.
- [List child executions of a batch — GET /api/v1/batches/{id}/executions](https://cascades.crscreditapi.com/docs/api/batches/list-batch-executions.md): Child rows ordered by row_index.
- [Cancel a batch — POST /api/v1/batches/{id}/cancel](https://cascades.crscreditapi.com/docs/api/batches/cancel-batch.md): Halts dispatch and propagates cancelled to in-flight and queued child executions.
- [Resume an interrupted batch — POST /api/v1/batches/{id}/resume](https://cascades.crscreditapi.com/docs/api/batches/resume-batch.md): Re-queues remaining children and restarts processing; poll getBatch.
- [Retry failed and skipped rows — POST /api/v1/batches/{id}/retry_failed](https://cascades.crscreditapi.com/docs/api/batches/retry-failed-batch.md): Bumps retry_count on failed rows under the per-row cap, requeues skipped rows, clears their stale terminal state, and restarts processing; poll getBatch.
- [Download flat results CSV — GET /api/v1/batches/{id}/exports.csv](https://cascades.crscreditapi.com/docs/api/batches/export-batch.md): One row per child execution by default.
- [Download structured ZIP of batch results — GET /api/v1/batches/{id}/exports.zip](https://cascades.crscreditapi.com/docs/api/batches/export-batch-zip.md): ZIP containing an error report, per-product CSVs, JSONs, and report PDFs.
- [Download all adverse-action notice PDFs as a ZIP — GET /api/v1/batches/{id}/adverse_action_notices.zip](https://cascades.crscreditapi.com/docs/api/batches/download-batch-adverse-action-notices.md): One entry per notice, prefixed with the applicant name.
- [List webhook subscriptions — GET /api/v1/webhook_subscriptions](https://cascades.crscreditapi.com/docs/api/webhooks/list-webhook-subscriptions.md): Subscriptions belonging to the calling api_client, newest first.
- [Create a webhook subscription — POST /api/v1/webhook_subscriptions](https://cascades.crscreditapi.com/docs/api/webhooks/create-webhook-subscription.md): Returns the signing_secret EXACTLY ONCE.
- [Show a webhook subscription — GET /api/v1/webhook_subscriptions/{id}](https://cascades.crscreditapi.com/docs/api/webhooks/get-webhook-subscription.md): Requires webhooks:read.
- [Update a webhook subscription — PATCH /api/v1/webhook_subscriptions/{id}](https://cascades.crscreditapi.com/docs/api/webhooks/update-webhook-subscription.md): Partial update of url, event_filter and active; omitted keys keep their value.
- [Delete a webhook subscription — DELETE /api/v1/webhook_subscriptions/{id}](https://cascades.crscreditapi.com/docs/api/webhooks/delete-webhook-subscription.md): Permanently deletes the subscription and its delivery log.
- [Rotate the signing secret — POST /api/v1/webhook_subscriptions/{id}/rotate_secret](https://cascades.crscreditapi.com/docs/api/webhooks/rotate-webhook-secret.md): Generates a new signing_secret (returned once, in this response) and preserves the previous one for 24 hours so deliveries during your deploy window ship with both v1= (new) and v0= (old) signatures.
- [List webhook deliveries — GET /api/v1/webhook_deliveries](https://cascades.crscreditapi.com/docs/api/webhooks/list-webhook-deliveries.md): Delivery attempts across all of the calling api_client's subscriptions, newest first.
- [Show a webhook delivery — GET /api/v1/webhook_deliveries/{id}](https://cascades.crscreditapi.com/docs/api/webhooks/get-webhook-delivery.md): Requires webhooks:read.
- [Manually retry a failed or dead delivery — POST /api/v1/webhook_deliveries/{id}/retry](https://cascades.crscreditapi.com/docs/api/webhooks/retry-webhook-delivery.md): Resets the delivery to pending and re-enqueues it immediately, outside the automatic retry schedule.

## MCP server

- [MCP server](https://cascades.crscreditapi.com/docs/mcp.md): Install the Cascades MCP server in Claude Code, Claude Desktop, Cursor, VS Code or Windsurf
- [cascades_create_workflow](https://cascades.crscreditapi.com/docs/mcp/tools/cascades_create_workflow.md): Create a new cascade (decision workflow) from a JSON definition, owned by the API key's account.
- [cascades_delete_workflow](https://cascades.crscreditapi.com/docs/mcp/tools/cascades_delete_workflow.md): Delete a cascade (soft-delete).
- [cascades_generate_workflow](https://cascades.crscreditapi.com/docs/mcp/tools/cascades_generate_workflow.md): Build a cascade from a plain-English policy description using the Cascades AI builder, then create it (by default) so it is immediately runnable with cascades_trigger_workflow.
- [cascades_get_execution](https://cascades.crscreditapi.com/docs/mcp/tools/cascades_get_execution.md): Fetch a single cascade execution by id to check its status and results.
- [cascades_get_workflow](https://cascades.crscreditapi.com/docs/mcp/tools/cascades_get_workflow.md): Fetch one cascade by id, including its full node graph (`definition`).
- [cascades_list_test_cases](https://cascades.crscreditapi.com/docs/mcp/tools/cascades_list_test_cases.md): List the pre-registered sandbox test-case subjects for a cascade — the synthetic applicants the CRS Testcase Service has authored for that cascade's products (e.g. specific credit-score bands).
- [cascades_list_workflows](https://cascades.crscreditapi.com/docs/mcp/tools/cascades_list_workflows.md): List the caller's saved Cascades (decision workflows) — their id, code, name, use_case, trigger_type, and whether each is active.
- [cascades_trigger_workflow](https://cascades.crscreditapi.com/docs/mcp/tools/cascades_trigger_workflow.md): Run a saved cascade for an applicant — i.e. start a decision.
- [cascades_update_workflow](https://cascades.crscreditapi.com/docs/mcp/tools/cascades_update_workflow.md): Update an existing cascade.

## Machine-readable

- [OpenAPI (JSON)](https://cascades.crscreditapi.com/openapi.json): The Cascades API spec, OpenAPI 3.0.3
- [OpenAPI (YAML)](https://cascades.crscreditapi.com/openapi.yaml): The same document as YAML
- [MCP server](https://cascades.crscreditapi.com/docs/mcp.md): Tool manifest and per-client install for the Cascades MCP server
- [AGENTS.md](https://cascades.crscreditapi.com/AGENTS.md): Skill file for coding agents — install, configure and call the API
- [Sitemap (markdown)](https://cascades.crscreditapi.com/sitemap.md): Every page grouped by section, linking the markdown twins
- [Sitemap (XML)](https://cascades.crscreditapi.com/sitemap.xml): Every docs URL with last-modified dates

## Optional

- [FCRA permissible purpose](https://cascades.crscreditapi.com/docs/compliance/fcra-permissible-purpose.md): Why every live report pull needs an FCRA permissible purpose, which purposes CRS certifies accounts for, and what that allows you to run through the API.
- [Adverse action notices](https://cascades.crscreditapi.com/docs/compliance/adverse-action-notices.md): What an FCRA adverse-action notice must contain, how Cascades' single-notice and employment flows meet it, the reason vocabulary, and what stays yours.
- [Changelog](https://cascades.crscreditapi.com/docs/changelog.md): What changed in the API, webhooks, MCP server and docs
- [2026-09-09 — Developer docs, OpenAPI operation ids and machine-readable twins](https://cascades.crscreditapi.com/docs/changelog/2026-09-09-docs-platform.md): New /docs site generated from the OpenAPI spec, operationIds on every operation, x-scopes and x-webhooks in the spec, markdown twins and llms.txt.
- [2026-09-04 — List a cascade's registered test-case subjects](https://cascades.crscreditapi.com/docs/changelog/2026-09-04-test-cases-endpoint.md): GET /workflows/{id}/test_cases returns the sandbox subjects registered for a cascade's products, each with a payload ready for trigger.