Duplicate a step

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

What this endpoint does

Copies one step, including its options, and stores the copy directly after the original on the main line. A router is copied with its branches and the steps inside them. Every reference between the copies is rewired, including a {{<stepId>.path}} template.

The copy is a new step with a new id, so the original is untouched and both can be edited independently.

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 NODE_NOT_FOUND`	The step is not part of this workflow	Read the workflow for its step ids.

Complete examples

{
  "data": {
    "node": {
      "_id": "65f1a2b3c4d5e6f708192a44",
      "name": "Read member XP (Copy)",
      "type": "platform-action",
      "order": 2,
      "continueOnFailure": false,
      "retryOnFailure": false,
      "options": {
        "action": "get-user-fields",
        "selectUser": { "type": "email", "value": ["{{65f1a2b3c4d5e6f708192a41.email}}"] },
        "fields": [{ "label": "Total XP", "field": "total_xp" }]
      }
    },
    "revision": "68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501",
    "redactedPaths": []
  }
}

Success and readback

HTTP 201 with the copy in { node, revision, redactedPaths }, and the revision in the ETag header. The copy carries a (Copy) suffix on its name and a new _id.

Read back with GET /{workflowId}: the copy must sit after the original, and any router copy must own copies of the branch steps, not the originals.

Errors and recovery

Status and code	When	Recovery
`400 VALIDATION_FAILED`	An id is not 24 hexadecimal characters	Use the ids exactly as returned.
`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.
`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 copies. A retry after a timeout can leave a duplicate, so read the workflow before resending.

Gotchas

The copy is inserted after the original on the main line, never inside a branch. To place a copy inside a branch, delete it and create it again with a branch position.

Credentials are copied as stored and are already redacted in the response. Nothing is re-supplied and nothing is revealed.

A Code step is copied like any other step, with its source, including when it sits inside a copied router.

Duplicating a router duplicates its branch structure, so the copy's branches and their members are independent of the original's.

Next steps

PATCH /{workflowId}/nodes/{nodeId} to change the copy.

POST /{workflowId}/nodes/{nodeId}/move to reposition it after creation.

POST /{workflowId}/validate before deploying.

Responses

🟢201201 Success

application/json

The copy, stored directly after the original.

Bodyapplication/json

🟠400400 VALIDATION_FAILED

🟠401401 AUTHENTICATION_REQUIRED / API_KEY_REQUIRED

🟠403403 API_KEY_PERMISSION_DENIED

🟠404404 NODE_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/duplicate' \ --header 'Authorization: Bearer <API_KEY>' \ --header 'If-Match: 162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c'

{ "data": { "node": { "_id": "65f1a2b3c4d5e6f708192a44", "name": "Read member XP (Copy)", "type": "platform-action", "order": 2, "continueOnFailure": false, "retryOnFailure": false, "options": { "action": "get-user-fields", "selectUser": { "type": "email", "value": [ "{{65f1a2b3c4d5e6f708192a41.email}}" ] }, "fields": [ { "label": "Total XP", "field": "total_xp" } ] } }, "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