--- title: Update a workflow — PATCH /api/v1/workflows/{id} description: "Partial update: only the keys present in the body change. To edit the graph, read it with getWorkflow, modify the array, and send the full definition back." canonical_url: "https://cascades.crscreditapi.com/docs/api/workflows/update-workflow" doc_version: "1.0.0" last_updated: "2026-10-09T18:04:24Z" source: "public/api-docs/v1/swagger.yaml#updateWorkflow" --- # Update a workflow — PATCH /api/v1/workflows/{id} `PATCH https://cascades.crscreditapi.com/api/v1/workflows/{id}` - Operation id: `updateWorkflow` - Scopes: `workflows:write` - Idempotent: no - MCP tool: `cascades_update_workflow` - OpenAPI: https://cascades.crscreditapi.com/openapi.json · https://cascades.crscreditapi.com/openapi.yaml (operationId `updateWorkflow`) Partial update: only the keys present in the body change. To edit the graph, read it with `getWorkflow`, modify the array, and send the full `definition` back. `PUT /workflows/{id}` is accepted as an alias with identical (partial) semantics. Setting `active: true` from an account without production access is refused with `403 activation_forbidden` rather than silently dropped. Requires `workflows:write`. ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | integer | yes | Workflow id. Only workflows owned by the token's account resolve; a foreign or deleted id returns 404. | ## Request body `application/json` — `WorkflowUpdateRequest` | Field | Type | Required | Description | |---|---|---|---| | `name` | string | no | | | `definition` | CascadeDefinition | no | Replacement node graph (the full array, not a diff). Read the current one with `getWorkflow` first. | | `use_case` | string, nullable | no | | | `trigger_type` | string | no | Unknown values are ignored (the current value is kept). One of: `"manual"`, `"event"`, `"scheduled"`. | | `active` | boolean | no | `true` activates, `false` makes it a draft. Activating requires production access (`403 activation_forbidden` otherwise). | ```json { "name": "Tenant Screening — Premium" } ``` ## Responses ### 200 — Updated workflow with definition `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | Workflow | 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 | | |   `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. | | `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": 27, "object": "workflow", "code": "TSS-27", "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", "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." } } ] }, "meta": { "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f" } } ``` ### 400 — `malformed_body` `application/json` — `ErrorEnvelope` ```json { "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` — `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 — `insufficient_scope` or `activation_forbidden` `application/json` — `ErrorEnvelope` ```json { "error": { "code": "activation_forbidden", "message": "Activating a cascade requires production access. It stays a draft, which runs in test mode.", "details": [ { "field": "active", "message": "requires production access" } ], "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f", "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/activation_forbidden" } } ``` ### 404 — Resource does not exist or belongs to another tenant / api_client `application/json` — `ErrorEnvelope` ```json { "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" } } ``` ### 422 — `validation_failed` `application/json` — `ErrorEnvelope` ```json { "error": { "code": "validation_failed", "message": "The workflow could not be updated.", "details": [ { "field": "definition", "message": "can only have one Applicant Source node" } ], "request_id": "7d4c2f48-9a1b-4c3d-8e2f-1a2b3c4d5e6f", "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/validation_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" } } ``` ## Code samples ### cURL ```shell curl -X PATCH "https://cascades.crscreditapi.com/api/v1/workflows/27" \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "name": "Tenant Screening — Premium" }' ``` ### Node.js ```javascript const response = await fetch("https://cascades.crscreditapi.com/api/v1/workflows/27", { method: "PATCH", headers: { "Authorization": "Bearer {{API_KEY}}", "Content-Type": "application/json" }, body: JSON.stringify({ "name": "Tenant Screening — Premium" }) }); const { data, meta } = await response.json(); console.log(response.status, data, meta.request_id); ``` ### Python ```python import requests response = requests.patch( "https://cascades.crscreditapi.com/api/v1/workflows/27", headers={ "Authorization": "Bearer {{API_KEY}}", }, json={ "name": "Tenant Screening — Premium" }, ) 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/27") request = Net::HTTP::Patch.new(uri) request["Authorization"] = "Bearer {{API_KEY}}" request["Content-Type"] = "application/json" request.body = <<~JSON { "name": "Tenant Screening — Premium" } 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(`{ "name": "Tenant Screening — Premium" }`) req, err := http.NewRequest("PATCH", "https://cascades.crscreditapi.com/api/v1/workflows/27", 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: # "Update a workflow 27 and summarise the result." # It will call the `cascades_update_workflow` tool with your key. ``` ## Related - [Cascades](https://cascades.crscreditapi.com/docs/concepts/cascades) ## Sitemap See the full [sitemap](https://cascades.crscreditapi.com/sitemap.md) for all pages.