---
title: Cascades
description: What a cascade is, the node grammar behind the definition array, and how to list, create, update, activate and delete cascades through the API.
canonical_url: "https://cascades.crscreditapi.com/docs/concepts/cascades"
doc_version: "1.0.0"
last_updated: "2026-09-23T19:55:02Z"
source: docs/concepts/cascades.md
---

# Cascades

A **cascade** is a decision workflow: which reports to pull, in what order, which rules to evaluate, and what happens on each outcome — approve, send to a reviewer, decline with an adverse-action notice. Operators usually author cascades in the visual builder; the API exposes the same objects (the resource is named `workflow`) so code and agents can list, run, create and edit them.

## What does a cascade look like over the API?

```json
{
  "id": 27,
  "object": "workflow",
  "name": "Tenant Screening Standard",
  "active": true,
  "trigger_type": "manual",
  "use_case": "tenant_screening",
  "created_at": "2026-05-08T18:41:05Z",
  "updated_at": "2026-05-08T18:41:05Z"
}
```

`GET /workflows/{id}` adds `definition`: the node graph as a JSON array. `active: false` marks a **draft** — drafts accept a single test-mode trigger but cannot run live, in batches, or be re-evaluated.

## What is in the definition?

`definition` is an array of nodes. Each node has an `id`, a `type`, and the edge keys that wire it to the next nodes. The vocabulary is fixed (it is the same grammar the AI generator and the validator use):

| Node type | Purpose | Required keys |
|---|---|---|
| `ApplicantSource` | Entry point; receives `payload.applicant` | — |
| `BillingProduct` | Pulls one report (credit, criminal, eviction, identity…) | `billing_product_code` |
| `IfElse` | Evaluates conditions and branches | `branches` |
| `Wait` | Pauses for a duration or until a date | `wait` |
| `GoTo` | Jumps to another node at runtime | `target_step` |
| `ShowResults` | Terminal node that surfaces the outcome | — |
| `Action` | Side effect chosen by `action_type` | `action_type` |

`Product` and `Condition` are accepted as legacy aliases for `BillingProduct` and `IfElse`.

**Action subtypes** (`action_type`): `Approve`, `SendEmail`, `AdverseAction`, `InternalNotification`.

**Edges.** `next_step` is the default forward edge. An `IfElse` fans out through `pass_steps`, `human_review_steps` and `fail_steps` — each an array of node ids. That placement is what gives downstream nodes their meaning: an `AdverseAction` under `fail_steps` auto-handles a decline; under `human_review_steps` it prepares a draft at flag time and waits for a reviewer to send it. See [Adverse action](/docs/concepts/adverse-action).

**Condition operators** inside `branches`: `equals`, `not_equals`, `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal`, `contains`, `not_contains`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty`, `is_true`, `is_false`. Fields are dotted paths into a product's output, e.g. `creditScore.fico9` or `searchSummary.recordsFound`.

A minimal, runnable definition:

```json
[
  { "id": "start",  "type": "ApplicantSource", "name": "Applicant", "next_step": ["credit"] },
  { "id": "credit", "type": "BillingProduct", "name": "Credit report",
    "billing_product_code": "TUC1001", "next_step": ["decide"] },
  { "id": "decide", "type": "IfElse", "name": "FICO gate",
    "branches": [{ "conditions": [{ "field": "creditScore.fico9", "operator": "greater_than_or_equal", "value": 680 }] }],
    "pass_steps": ["approve"], "human_review_steps": [], "fail_steps": ["done"] },
  { "id": "approve", "type": "Action", "action_type": "Approve", "name": "Approve", "next_step": ["done"] },
  { "id": "done", "type": "ShowResults", "name": "Results", "next_step": [] }
]
```

The full schema is [`CascadeDefinition`](/docs/api/schemas/CascadeDefinition) in the reference.

## How do I list and read cascades?

`GET /workflows` returns the cascades your key's user owns, newest first, paginated. Filter with `filter[active]=true`, `filter[use_case]=tenant_screening` or `filter[trigger_type]=manual`. `GET /workflows/{id}` returns one with its `definition`. Both need `workflows:read`.

Cascades belong to the **user** behind your key, so two API clients of the same account see the same cascades; executions, by contrast, are isolated per client. See [Keys, scopes and rate limits](/docs/concepts/scopes-and-keys).

## How do I create or change one?

- `POST /workflows` with `name` and `definition` (and optionally `active`, `trigger_type`, `use_case`) creates a cascade. Needs `workflows:write`. The definition is validated against the grammar and against the products your account can use; failures come back as `422 validation_failed` with one `details` entry per problem.
- `PATCH /workflows/{id}` changes only the fields you send. To edit the graph, read it, modify the array, and send the whole `definition` back.
- `DELETE /workflows/{id}` soft-deletes: the cascade disappears from lists and can no longer be triggered; its past executions remain readable.
- `POST /workflows/generate` builds a definition from a plain-English prompt — see [Generate a cascade with AI](/docs/guides/ai-generate-a-cascade).

### Activation is gated

On an unapproved (sandbox) account a new cascade is always saved as a draft, whatever `active` says, and the response carries a `note` explaining that; `PATCH` with `active: true` is refused with `403 activation_forbidden`. Drafts still run in test mode. Once the account is approved, `active: true` works and live runs become possible. See [Sandbox vs live](/docs/concepts/sandbox-vs-live).

## Templates

`GET /workflow_templates` is a read-only catalog of published cascades. Copy a template's `definition` into `POST /workflows` to start from something that works.

## Related

- [Executions](/docs/concepts/executions) — running a cascade and reading the outcome
- [`POST /workflows/{id}/trigger`](/docs/api/workflows/trigger-workflow)
- [Human review](/docs/concepts/human-review) and [Adverse action](/docs/concepts/adverse-action) — what the branch placement means at runtime

## Sitemap

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