Duplicate a router branch

POST /{workflowId}/nodes/{nodeId}/branches/{branchIndex}/duplicate needs workflowBuilder.

What this endpoint does

Copies one branch, including the steps that belong to it, and appends the copy to the router. The copy's steps are new steps with new ids, and references between them are rewired to the copies, including a {{<stepId>.path}} template.

Use it to build a variant quickly: duplicate a branch, change its conditions, and add it as another case.

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.

Failure	Meaning	Recovery
`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"] },
          { "branchName": "XP > 100 (Copy)", "branchType": "CONDITION", "workflowNodeIds": ["65f1a2b3c4d5e6f708192a4a"] }
        ]
      }
    },
    "revision": "68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501",
    "redactedPaths": []
  }
}

Success and readback

HTTP 201 with the router step and the workflow's new revision. The response is the readback: the copied branch is the last entry in options.branches, with a (Copy) suffix and its own member ids.

Read GET /{workflowId} to see the copied steps nested under the new branch. They carry new ids, so anything that referenced the originals still points at the originals.

Errors and recovery

Status and code	When	Recovery
`400 VALIDATION_FAILED`	The step is not a router, or an id is malformed	Use a router step and valid ids.
`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

Not idempotent: two accepted calls create two branches. A retry after a timeout can leave a duplicate, so read the router before resending.

Gotchas

The copy has the same conditions as the original. Change them, or the second branch can never be reached when executePaths is first_matching.

The copied branch is appended last, so a duplicated fallback ends up after the original fallback and never runs.

Credentials inside copied steps are copied as stored and are redacted in the response.

A Code step inside the copied branch is copied like any other step, with its source.

Next steps

PATCH /{workflowId}/nodes/{nodeId}/branches/{branchIndex} to give the copy its own conditions and name.

POST /{workflowId}/validate before deploying.

POST /{workflowId}/nodes/{nodeId}/branches/{branchIndex}/duplicate again for a third variant.

Responses

🟢201201 Success

application/json

The router step with the copied branch, including copies of its steps.

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 POST 'https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes/65f1a2b3c4d5e6f708192a3c/branches/0/duplicate' \ --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": "XP > 100", "branchType": "CONDITION", "workflowNodeIds": [] }, { "branchName": "XP > 100 (Copy)", "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