Delete a router branch

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

What this endpoint does

Removes one branch from a router step and deletes the steps that belonged to it. The remaining branches keep their relative order, and the router's branch list is rewritten without the branch you removed.

A router must keep at least one branch, so deleting the last one is refused.

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.

Branch indexes shift after a delete, so read the router before deleting to be sure which branch you are removing.

Failure	Meaning	Recovery
`400 VALIDATION_FAILED`	The delete would leave the router with no branches	Add the replacement branch first.
`404 BRANCH_NOT_FOUND`	No branch at that index	Read the router and use an existing index.

Complete examples

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

Success and readback

HTTP 200 with the router step and the workflow's new revision. The response is the readback: options.branches no longer contains the deleted branch, and the surviving branches are in their stored order.

The steps of the deleted branch are gone from the workflow. Read GET /{workflowId} to confirm they are absent from nodes, and run POST /{workflowId}/validate in case another step referenced one of them.

Errors and recovery

Status and code	When	Recovery
`400 VALIDATION_FAILED`	The router would be left with no branches	Add the replacement branch, then delete.
`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.

Retry safety

A second delete of the same index deletes a different branch if the list shifted, because the index is positional. Read the router before retrying, and send the revision you just read.

Gotchas

The step ids of the deleted branch are gone. Any reference to them becomes unresolved, and POST /{workflowId}/validate reports it as a warning. Deploy still proceeds, so fix the references before the next run.

Branch indexes shift after the delete. Never reuse an index from before the call.

Deleting a branch is irreversible. Export the workflow first if the branch is worth recovering.

A fallback branch is just another branch here: deleting it leaves only condition branches, which is valid.

Next steps

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

POST /{workflowId}/validate to see references the delete broke.

GET /{workflowId} for the new revision.

Responses

🟢200200 Success

application/json

The router step after the branch and its steps were removed.

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

🟠429429 RATE_LIMITED

🔴500500 INTERNAL_ERROR

🔴503503 LOCK_UNAVAILABLE

curl --location --request DELETE 'https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes/65f1a2b3c4d5e6f708192a3c/branches/0' \ --header 'Authorization: Bearer <API_KEY>' \ --header 'If-Match: 162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c'

{ "data": { "node": { "_id": "65f1a2b3c4d5e6f708192a3c", "name": "XP over 100?", "type": "router", "order": 1, "continueOnFailure": false, "retryOnFailure": false, "options": { "executePaths": "first_matching", "branches": [ { "branchName": "Otherwise", "branchType": "FALLBACK", "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