---
title: Cascades API
description: Run tenant, employment and credit screening decisions through one REST API and MCP server. Start in the sandbox, go live when approved.
canonical_url: "https://cascades.crscreditapi.com/docs"
doc_version: "1.0.0"
last_updated: "2026-10-05T19:24:37Z"
source: docs/index.md
---

# Cascades API

Cascades runs **decision workflows** ("cascades") against an applicant: pull the reports the cascade asks for — credit, criminal, eviction, identity — evaluate the operator's rules, and land on a decision. The API lets your systems trigger those runs, read the outcome, pause for a human reviewer, and receive signed lifecycle events. The MCP server exposes the same surface to coding agents and assistants.

## What can I do with the API?

| You want to | Use |
|---|---|
| Start a screening for one applicant | [`POST /workflows/{id}/trigger`](/docs/api/workflows/trigger-workflow) |
| Read the decision and per-step outputs | [`GET /executions/{id}`](/docs/api/executions/get-execution) |
| Screen hundreds of applicants at once | [`POST /workflows/{id}/batches`](/docs/api/batches/create-batch) |
| Let a person approve or deny a paused run | [`POST /executions/{id}/review_decisions`](/docs/api/executions/submit-review-decision) |
| Be told when a run finishes | [Webhooks](/docs/concepts/webhooks) |
| Build or edit a cascade from code or an agent | [`POST /workflows`](/docs/api/workflows/create-workflow), [`POST /workflows/generate`](/docs/api/workflows/generate-workflow) |
| Download the report and adverse-action PDFs | [Artifacts](/docs/api/executions/list-report-artifacts) |

## How do I integrate, in order?

1. **Mint a sandbox key** at [/api-keys](/api-keys). It carries every scope and expires in 90 days. See [Keys, scopes and rate limits](/docs/concepts/scopes-and-keys).
2. **Subscribe a webhook** with [`POST /webhook_subscriptions`](/docs/api/webhooks/create-webhook-subscription) and store the `signing_secret` — it is shown once.
3. **Trigger a run** with a unique `Idempotency-Key` and your own `external_reference` so you can correlate results.
4. **Poll or wait**: `trigger` answers `202 Accepted`. Poll `GET /executions/{id}` until `status` is terminal, or wait for `execution.completed`.
5. **Handle human review** if the cascade has a review node: the run pauses at `awaiting_review` until someone decides.
6. **Go live** once your account is approved: switch `execution_mode` to `live`. Until then every run uses synthetic data and never bills.

```bash
curl -X POST "https://cascades.crscreditapi.com/api/v1/workflows/27/trigger" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rv-app-20491" \
  -d '{ "payload": { "applicant": { "first_name": "Jordan", "last_name": "Lee" } }, "execution_mode": "test" }'
```

The full walkthrough, with a Node, Python, Ruby and MCP version of every step, is the [quickstart](/docs/quickstart).

## What does a response look like?

Every success is `{ "data": …, "meta": { "request_id": … } }`; collections add `page`, `per_page`, `total_count`, `total_pages` and `object` to `meta`. Every error is `{ "error": { "code", "message", "details", "request_id", "doc_url" } }`, and `doc_url` links to the page for that code under [Errors](/docs/api/errors). Keep `request_id` in your logs — support correlates on it.

## Where is the reference?

- [API reference](/docs/api) — every endpoint, generated from the [OpenAPI spec](/openapi.json).
- [Webhook events](/docs/api/webhooks) — the catalog, signing scheme and retry schedule.
- [MCP server](/docs/mcp) — install the `@crscreditapi/cascades-mcp-server` package into Claude Code, Cursor or VS Code.
- [Changelog](/docs/changelog) — what changed, newest first.

## Docs for agents

Everything on this site is available in a form a coding agent or an LLM can read without scraping HTML:

- [/llms.txt](/llms.txt) — a short index of every page with a one-line description, the place to point an agent first.
- [/llms-full.txt](/llms-full.txt) — the whole site as one markdown document, for a single-fetch context load.
- [/openapi.json](/openapi.json) (also [/openapi.yaml](/openapi.yaml)) — the OpenAPI 3.0 spec the reference is generated from, with `operationId`, `x-scopes`, `x-async` and `x-webhooks`.
- **Markdown twins** — append `.md` to any docs URL (`/docs/concepts/executions.md`) or send `Accept: text/markdown` to get the page as clean markdown with front matter.
- [/docs/mcp](/docs/mcp) — the MCP server that wraps the API as tools for Claude Code, Cursor, VS Code and other clients, with per-client install pages.

## Sitemap

See the full [sitemap](https://cascades.crscreditapi.com/sitemap.md) for all pages.