Update a router branch

PATCH /{workflowId}/nodes/{nodeId}/branches/{branchIndex} needs workflowBuilder.

What this endpoint does

Changes a branch's name, its type, or its condition groups. Fields you omit are kept, so this is a partial update of one branch rather than a replacement of the router.

The branch keeps its index and its steps. Changing a branch from CONDITION to FALLBACK does not move or delete the steps attached to it.

Quick start

Authentication and permission

Authorization: Bearer <API_KEY> with workflowBuilder, on a workflow of the key's community. If-Match is optional. Send the revision you read to avoid overwriting a concurrent change (a stale value is refused with 409 VERSION_CONFLICT); omit it and your write wins as the last one. A deployed workflow is edited with the same call: the change applies immediately.

The branch index is positional, so it shifts when another branch is added or deleted. Read the router before writing to be sure which branch you are changing.

Failure	Meaning	Recovery
`404 BRANCH_NOT_FOUND`	No branch at that index	Read the router and use an existing index.

Complete examples

Replace the condition groups of the first branch:

{
  "data": {
    "node": {
      "_id": "65f1a2b3c4d5e6f708192a3e",
      "name": "XP over 100?",
      "type": "router",
      "order": 2,
      "continueOnFailure": false,
      "retryOnFailure": false,
      "options": {
        "executePaths": "first_matching",
        "branches": [
          { "branchName": "XP at least 100", "branchType": "CONDITION", "workflowNodeIds": ["65f1a2b3c4d5e6f708192a3d"] },
          { "branchName": "Otherwise", "branchType": "FALLBACK", "workflowNodeIds": [] }
        ]
      }
    },
    "revision": "68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501",
    "redactedPaths": []
  }
}

Success and readback

HTTP 200 with the router step and the workflow's new revision. The response is the readback for the branch you changed: name, type and condition groups as stored, and the same member ids as before.

Run POST /{workflowId}/validate after a condition change. A group that uses OR or WHERE is reported as ROUTER_OPERATOR_UNSAFE, as a warning: the runtime treats those groups as always true, so the branch fires more often than you meant. Deploy proceeds either way, so act on the warning.

Errors and recovery

Status and code	When	Recovery
`400 VALIDATION_FAILED`	An empty body, or a field with an invalid value	Send at least one of `branchName`, `branchType`, `conditions`.
`401 AUTHENTICATION_REQUIRED`	No key, or an unknown key	Send a valid key.
`403 API_KEY_PERMISSION_DENIED`	No `workflowBuilder`	Grant the permission.
`404 NODE_NOT_FOUND`	The step is not part of this workflow	Read the workflow for its step ids.
`404 BRANCH_NOT_FOUND`	No branch at that index	Read the router and use an existing index.
`409 VERSION_CONFLICT`	You sent an `If-Match` that is not the current revision. `meta.currentRevision` carries the live value	Re-read and resend.

| 415 UNSUPPORTED_MEDIA_TYPE | The body was not declared application/json | Send the header. |

Retry safety

A retry with the same If-Match is refused with 409 VERSION_CONFLICT once the first attempt landed, so a duplicate edit cannot apply twice. Sending the same body again against the new revision is a no-op that changes nothing.

Gotchas

conditions is replaced, not merged. Send the complete condition tree you want.

Conditions are AND inside a group. OR and WHERE groups are stored, and validation reports them as warnings rather than refusing the write or the deploy.

Renaming a branch does not change its index or its steps.

A branch index is not stable across adds and deletes. Never cache it across calls.

A router with only a fallback branch is valid, deploys, and simply always takes the fallback.

Next steps

POST /{workflowId}/nodes/{nodeId}/branches to add another branch.

POST /{workflowId}/nodes with position: {routerNodeId, branchIndex} to add a step here.

POST /{workflowId}/validate before deploying.

Responses

🟢200200 Success

application/json

The router step after the change.

Bodyapplication/json

🟠400400 VALIDATION_FAILED

🟠401401 AUTHENTICATION_REQUIRED / API_KEY_REQUIRED

🟠403403 API_KEY_PERMISSION_DENIED

🟠404404 BRANCH_NOT_FOUND

🟠409409 VERSION_CONFLICT / WORKFLOW_LOCKED

🟠413413 VALIDATION_FAILED

🟠415415 UNSUPPORTED_MEDIA_TYPE

🟠429429 RATE_LIMITED

🔴500500 INTERNAL_ERROR

🔴503503 LOCK_UNAVAILABLE

curl --location --request PATCH 'https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes/65f1a2b3c4d5e6f708192a3c/branches/0' \ --header 'Authorization: Bearer <API_KEY>' \ --header 'If-Match: 162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c' \ --header 'Content-Type: application/json' \ --data '{ "branchName": "XP at least 100" }'

{ "data": { "node": { "_id": "65f1a2b3c4d5e6f708192a3c", "name": "XP over 100?", "type": "router", "order": 1, "continueOnFailure": false, "retryOnFailure": false, "options": { "executePaths": "first_matching", "branches": [ { "branchName": "XP at least 100", "branchType": "CONDITION", "workflowNodeIds": [] } ] } }, "revision": "68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501", "redactedPaths": [] } }

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request