--- title: Generate a workflow from a prompt — POST /api/v1/workflows/generate description: Builds a cascade definition from a plain-English policy description using the AI builder, validates it (with one automatic repair pass), and — by default… canonical_url: "https://cascades.crscreditapi.com/docs/api/workflows/generate-workflow" doc_version: "1.0.0" last_updated: "2026-10-09T18:04:24Z" source: "public/api-docs/v1/swagger.yaml#generateWorkflow" --- # Generate a workflow from a prompt — POST /api/v1/workflows/generate `POST https://cascades.crscreditapi.com/api/v1/workflows/generate` - Operation id: `generateWorkflow` - Scopes: `workflows:write` - Idempotent: no - MCP tool: `cascades_generate_workflow` - OpenAPI: https://cascades.crscreditapi.com/openapi.json · https://cascades.crscreditapi.com/openapi.yaml (operationId `generateWorkflow`) 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 `createWorkflow` (same draft rule for sandbox accounts, same `note`). Pass `create: false` to receive the generated definition as a preview without saving anything. Generation shares a small concurrency budget with the in-app designer; when every slot is busy the call returns `503 designer_busy` and should be retried after a short delay. Requires `workflows:write`. ## Request body `application/json` — `WorkflowGenerateRequest` | Field | Type | Required | Description | |---|---|---|---| | `prompt` | string | yes | Plain-English description of the decision policy to turn into a cascade (max 5 000 characters by default). | | `name` | string | no | Optional name override; otherwise the generator names the cascade. | | `use_case` | string | no | Optional use case label. Defaults to `tenant_screening`. | | `create` | boolean | no | `true` (default) saves the generated cascade and returns `201`; `false` returns the generated definition as a `200` preview without saving. | ```json { "prompt": "Pull an Equifax credit report. Approve if FICO is at least 650; otherwise send an adverse-action notice for review.", "use_case": "tenant_screening" } ``` ## Responses ### 201 — Generated and saved. `generation` describes the AI pass; `note` appears for sandbox accounts (draft). `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | Workflow + SandboxDraftNote | no | | |   `id` | integer | yes | | |   `object` | string | yes | | |   `code` | string, nullable | no | Short human-readable code assigned by Cascades. | |   `name` | string | yes | | |   `active` | boolean | yes | `true` = activated and triggerable in live mode. Drafts (`false`) can still be triggered in test mode. | |   `trigger_type` | string | yes | One of: `"manual"`, `"event"`, `"scheduled"`. | |   `use_case` | string, nullable | no | | |   `created_at` | string (date-time) | no | | |   `updated_at` | string (date-time) | no | | |   `generation` | CascadeGeneration | no | Metadata about the AI generation that produced a definition. | |     `name` | string | no | The name the generator chose. | |     `model` | string | no | The model that produced the definition. | |     `repaired` | boolean | no | `true` when the first draft failed validation and a repair pass fixed it. | |     `warnings` | array of CascadeGenerationWarning | no | Non-blocking findings from the definition validator (unreachable nodes, compliance hints). | |       `node_id` | string | yes | The `id` of the node the finding is about. | |       `code` | string | yes | Machine-readable finding. Current codes: `unreachable_node`, `missing_adverse_action`, `generic_adverse_action_reason`, `folded_thresholds`, `jurisdiction_review`. | |       `message` | string | yes | Human-readable explanation with the suggested fix. | |   `note` | string | no | Present only when the account lacks production access and the cascade was therefore created as a draft. | | `meta` | Meta | no | | |   `request_id` | string | yes | Correlation id for this request. Also sent as the `X-Request-Id` response header; quote it when contacting support. | ```json { "data": { "id": 42, "object": "workflow", "code": "FCS-42", "name": "FICO 650 Screening", "active": true, "trigger_type": "manual", "use_case": "tenant_screening", "created_at": "2026-09-09T14:10:00Z", "updated_at": "2026-09-09T14:10:00Z", "generation": { "name": "FICO 650 Screening", "model": "claude-opus-4-8", "repaired": false, "warnings": [] } }, "meta": { "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f" } } ``` ### 200 — Preview (`create: false`). Nothing was saved. `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | CascadeGenerationPreview | no | Returned by `generateWorkflow` when `create` is `false`. Nothing is saved. | |   `object` | string | no | One of: `"cascade_generation"`. | |   `definition` | array of CascadeNode | no | A cascade's node graph: an ordered array of `CascadeNode` objects. Exactly one `ApplicantSource` node is the entry point; every other node is reached through the edge keys (`next_step`, `pass_steps`, `human_review_steps`, `fail_steps`), each of which is an array of node `id`s that must resolve within the same array. An empty array is accepted on create/update (an empty draft) but cannot be run. | |     `id` | string | yes | Unique within the definition, e.g. `step_credit`. Edge keys reference nodes by this value. | |     `type` | string | yes | One of: `"ApplicantSource"`, `"BillingProduct"`, `"Product"`, `"IfElse"`, `"Condition"`, `"Wait"`, `"GoTo"`, `"ShowResults"`, `"Action"`. | |     `name` | string | no | Human-readable label shown in the builder and in `step_outputs`. | |     `next_step` | array of string | no | Default forward edge — ids of the node(s) to run next. | |     `billing_product_code` | string | no | `BillingProduct` / `Product` only. The product to pull, e.g. `EQF1003` (Equifax credit), `TUC1001` (TransUnion credit), `CIC4002` (criminal), `CIC4003` (eviction). May also be nested as `config.billing_product_code`. | |     `config` | object | no | Optional per-node configuration. `store_result_as` names the key under which a product's output is stored. | |       `store_result_as` | string | no | | |       `billing_product_code` | string | no | Alternative location for `billing_product_code`. | |     `branches` | object | no | `IfElse` / `Condition` only. Conditions for the `pass` branch and (optionally) the `human_review` branch; anything that matches neither takes `fail_steps`. | |       `pass` | CascadeBranch | no | A branch of an `IfElse` node — one or more condition groups combined with `group_logic`. | |         `group_logic` | string | no | How the condition groups combine. Defaults to `and`. One of: `"and"`, `"or"`. | |         `condition_groups` | array of object | no | | |           `logic` | string | no | How the conditions inside this group combine. Defaults to `and`. One of: `"and"`, `"or"`. | |           `conditions` | array of CascadeCondition | yes | | |             `source_node_id` | string | yes | The `id` of the product node whose output is compared. | |             `field` | string | yes | Exact output field path from that product's schema, e.g. `creditScore.fico9`. | |             `operator` | string | yes | One of: `"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"`. | |             `value` | one of | no | The comparison value. Required for every operator except the unary ones (`is_empty`, `is_not_empty`, `is_true`, `is_false`), which accept `null` or no `value` at all. | |       `human_review` | CascadeBranch | no | A branch of an `IfElse` node — one or more condition groups combined with `group_logic`. | |         `group_logic` | string | no | How the condition groups combine. Defaults to `and`. One of: `"and"`, `"or"`. | |         `condition_groups` | array of object | no | | |           `logic` | string | no | How the conditions inside this group combine. Defaults to `and`. One of: `"and"`, `"or"`. | |           `conditions` | array of CascadeCondition | yes | | |             `source_node_id` | string | yes | The `id` of the product node whose output is compared. | |             `field` | string | yes | Exact output field path from that product's schema, e.g. `creditScore.fico9`. | |             `operator` | string | yes | One of: `"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"`. | |             `value` | one of | no | The comparison value. Required for every operator except the unary ones (`is_empty`, `is_not_empty`, `is_true`, `is_false`), which accept `null` or no `value` at all. | |     `pass_steps` | array of string | no | `IfElse` only. Node ids to run when the `pass` branch matches. | |     `human_review_steps` | array of string | no | `IfElse` only. Node ids to run when the `human_review` branch matches; the execution pauses with `needs_human_review: true` until a review decision resumes it. | |     `fail_steps` | array of string | no | `IfElse` only. Node ids to run when no branch matches. | |     `action_type` | string | no | `Action` only. One of: `"Approve"`, `"SendEmail"`, `"AdverseAction"`, `"InternalNotification"`. | |     `email` | object | no | `Action` with `action_type: SendEmail`. Fields support `{{variable}}` interpolation from the execution context. | |       `to` | string | no | | |       `subject` | string | no | | |       `body` | string | no | | |     `adverse_action` | object | no | `Action` with `action_type: AdverseAction`. `send_strategy: draft_first` parks the notice for human review before sending. | |       `recipient` | string | no | | |       `action_taken` | string | no | The action box ticked on the notice: `denied` (application denied), `revoked` (credit revoked or terms changed unfavorably), `adverse_employment` (adverse employment action) or `other_action`. Cascades the AI designer generates always use `denied`. One of: `"denied"`, `"revoked"`, `"adverse_employment"`, `"other_action"`. | |       `send_strategy` | string | no | One of: `"draft_first"`, `"auto_send"`. | |       `reason` | string | no | | |     `internal_notification` | object | no | `Action` with `action_type: InternalNotification`. Operator-facing notification settings. | |     `wait` | object | no | `Wait` only. The delay before the next node runs. | |       `duration` | number | no | | |       `unit` | string | no | One of: `"seconds"`, `"minutes"`, `"hours"`, `"days"`, `"weeks"`. | |     `target_step` | string | no | `GoTo` only. The node id to jump to. | |   `valid` | boolean | no | Whether the definition passed the validator. | |   `name` | string | no | | |   `model` | string | no | | |   `repaired` | boolean | no | | |   `warnings` | array of CascadeGenerationWarning | no | | |     `node_id` | string | yes | The `id` of the node the finding is about. | |     `code` | string | yes | Machine-readable finding. Current codes: `unreachable_node`, `missing_adverse_action`, `generic_adverse_action_reason`, `folded_thresholds`, `jurisdiction_review`. | |     `message` | string | yes | Human-readable explanation with the suggested fix. | | `meta` | Meta | no | | |   `request_id` | string | yes | Correlation id for this request. Also sent as the `X-Request-Id` response header; quote it when contacting support. | ```json { "data": { "object": "cascade_generation", "definition": [ { "id": "step_applicant", "type": "ApplicantSource", "name": "Applicant", "next_step": [ "step_credit" ] }, { "id": "step_credit", "type": "BillingProduct", "name": "Credit report", "billing_product_code": "EQF1003", "next_step": [ "step_score_check" ] }, { "id": "step_score_check", "type": "IfElse", "name": "Score at least 650?", "branches": { "pass": { "group_logic": "and", "condition_groups": [ { "logic": "and", "conditions": [ { "source_node_id": "step_credit", "field": "creditScore.fico9", "operator": "greater_than_or_equal", "value": 650 } ] } ] } }, "pass_steps": [ "step_approve" ], "fail_steps": [ "step_adverse_action" ] }, { "id": "step_approve", "type": "Action", "name": "Approve", "action_type": "Approve" }, { "id": "step_adverse_action", "type": "Action", "name": "Adverse action", "action_type": "AdverseAction", "adverse_action": { "recipient": "{{applicant.email}}", "action_taken": "denied", "send_strategy": "draft_first", "reason": "Credit score below the minimum required for this property." } } ], "valid": true, "name": "string", "model": "string", "repaired": true, "warnings": [ { "node_id": "step_fico_check", "code": "missing_adverse_action", "message": "Decision node \"step_fico_check\" has a fail branch that does not end in an AdverseAction. FCRA declines should send an adverse-action notice." } ] }, "meta": { "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f" } } ``` ### 401 — Missing, malformed, expired or revoked bearer token. The `WWW-Authenticate` header carries the RFC 6750 challenge. `application/json` — `ErrorEnvelope` ```json { "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 — Token does not hold the required scope. `details` lists the scope(s) that were checked. `application/json` — `ErrorEnvelope` ```json { "error": { "code": "insufficient_scope", "message": "This token does not have the required scope.", "details": [ { "field": "scope", "message": "executions:write" } ], "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f", "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/insufficient_scope" } } ``` ### 422 — `validation_failed` (blank or over-long `prompt`, or the saved workflow failed validation) or `generation_failed` (the model could not produce a valid definition; `details` lists the validator's findings). `application/json` — `ErrorEnvelope` ```json { "error": { "code": "generation_failed", "message": "The generated cascade did not pass validation.", "details": [ { "field": "definition", "message": "Decision node \"step_score_check\" uses operator \">=\", which is not valid." } ], "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f", "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/generation_failed" } } ``` ### 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` — `ErrorEnvelope` ```json { "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" } } ``` ### 503 — `designer_busy` — every generation slot is in use. Retry after a few seconds. `application/json` — `ErrorEnvelope` ```json { "error": { "code": "designer_busy", "message": "The cascade designer is busy right now. Please try again in a moment.", "details": [], "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f", "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/designer_busy" } } ``` ## Code samples ### cURL ```shell curl -X POST "https://cascades.crscreditapi.com/api/v1/workflows/generate" \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Pull an Equifax credit report. Approve if FICO is at least 650; otherwise send an adverse-action notice for review.", "use_case": "tenant_screening" }' ``` ### Node.js ```javascript const response = await fetch("https://cascades.crscreditapi.com/api/v1/workflows/generate", { method: "POST", headers: { "Authorization": "Bearer {{API_KEY}}", "Content-Type": "application/json" }, body: JSON.stringify({ "prompt": "Pull an Equifax credit report. Approve if FICO is at least 650; otherwise send an adverse-action notice for review.", "use_case": "tenant_screening" }) }); const { data, meta } = await response.json(); console.log(response.status, data, meta.request_id); ``` ### Python ```python import requests response = requests.post( "https://cascades.crscreditapi.com/api/v1/workflows/generate", headers={ "Authorization": "Bearer {{API_KEY}}", }, json={ "prompt": "Pull an Equifax credit report. Approve if FICO is at least 650; otherwise send an adverse-action notice for review.", "use_case": "tenant_screening" }, ) response.raise_for_status() payload = response.json() print(payload["data"], payload["meta"]["request_id"]) ``` ### Ruby ```ruby require "net/http" require "json" uri = URI("https://cascades.crscreditapi.com/api/v1/workflows/generate") request = Net::HTTP::Post.new(uri) request["Authorization"] = "Bearer {{API_KEY}}" request["Content-Type"] = "application/json" request.body = <<~JSON { "prompt": "Pull an Equifax credit report. Approve if FICO is at least 650; otherwise send an adverse-action notice for review.", "use_case": "tenant_screening" } JSON response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http| http.request(request) end payload = JSON.parse(response.body) puts payload["data"], payload.dig("meta", "request_id") ``` ### Go ```go package main import ( "bytes" "fmt" "io" "net/http" ) func main() { body := []byte(`{ "prompt": "Pull an Equifax credit report. Approve if FICO is at least 650; otherwise send an adverse-action notice for review.", "use_case": "tenant_screening" }`) req, err := http.NewRequest("POST", "https://cascades.crscreditapi.com/api/v1/workflows/generate", bytes.NewBuffer(body)) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer {{API_KEY}}") req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() out, _ := io.ReadAll(resp.Body) fmt.Println(resp.StatusCode, string(out)) } ``` ### Agent ```shell claude mcp add cascades \ -e CASCADES_API_KEY={{API_KEY}} \ -e CASCADES_PROD_BASE_URL=https://cascades.crscreditapi.com \ -- npx -y @crscreditapi/cascades-mcp-server # Then ask your assistant: # "Generate a workflow from a prompt and summarise the result." # It will call the `cascades_generate_workflow` tool with your key. ``` ## Related - [Generate a cascade with AI](https://cascades.crscreditapi.com/docs/guides/ai-generate-a-cascade) ## Sitemap See the full [sitemap](https://cascades.crscreditapi.com/sitemap.md) for all pages.