API reference / Workflow Builder

Reorder a main-line step

Moves one main-line step to a new place on the main line.

Last updated 28 Oct 2026API v1

Method: POST
Path: https://api.returning.ai/v1/workflow-builder/data-workflows/{workflowId}/nodes/{nodeId}/move
Permission: workflowBuilder
Retries: Send If-Match if a duplicate move matters: a retry with the same revision is refused with 409 VERSION_CONFLICT after the first attempt lands.

Authentication#

Header: Authorization: Bearer <API_KEY>
Permission: workflowBuilder

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
`400 VALIDATION_FAILED`	`nodeId` is not on the main line, or `after` names a step that is not on the main line	Read the workflow and pick a main-line step.

Behaviour#

The whole main line is renumbered from 1 so the order is always a clean sequence, and the workflow's authored order is rewritten to match.

It moves within the main line only. A step inside a router branch cannot be moved with this route, and a main-line step cannot be moved into a branch.

Request#

Path parameters#

workflowId#stringREQUIRED

Workflow identifier: 24 hexadecimal characters, as returned in _id.

Rule^[0-9a-fA-F]{24}$

Eg65f1a2b3c4d5e6f708192a3b

nodeId#stringREQUIRED

Step identifier: 24 hexadecimal characters, as returned in the step's _id.

Rule^[0-9a-fA-F]{24}$

Eg65f1a2b3c4d5e6f708192a3c

Headers#

Authorization#stringREQUIRED

Community API key: Bearer <API_KEY>.

EgBearer <API_KEY>

If-Match#stringOPTIONAL

Optional. Send the revision the change is based on, bare or quoted, to avoid overwriting a concurrent change: a stale value is refused with 409 VERSION_CONFLICT. Omit it for last-write-wins.

Eg162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c

Content-Type#stringREQUIRED

Request body format.

Ruleapplication/json

Body#

after#stringREQUIRED

Step id to move after, or trigger for the first position.

Eg"trigger"

Watch for

after: "trigger" means the first position on the main line. Any other value must be a main-line step id.
Branch members are not renumbered by this route, and their relative order inside the branch is preserved.
Moving across branches is a delete plus a create, because no move exists for that case. Recreate the step inside the target branch with position: {routerNodeId, branchIndex}.
A move renumbers every main-line step, so any external note that stored order values is stale afterwards.
The route returns the workflow, not the step, so a client that only reads data.node finds nothing here.

More examples and details

Move a step to the front:

BASH

curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes/65f1a2b3c4d5e6f708192a3d/move" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --header "If-Match: 162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c" \
  --data '{"after":"trigger"}'

Move it after another step:

BASH

curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes/65f1a2b3c4d5e6f708192a3d/move" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --header "If-Match: 68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501" \
  --data '{"after":"65f1a2b3c4d5e6f708192a3c"}'

JSON

{
  "data": {
    "_id": "65f1a2b3c4d5e6f708192a3b",
    "communityId": "65f1a2b3c4d5e6f708192a50",
    "name": "VIP bonus",
    "status": "draft",
    "outgoingWebhookUrl": null,
    "createdAt": "2026-10-24T09:15:00.000Z",
    "updatedAt": "2026-10-24T12:40:11.000Z",
    "trigger": null,
    "nodes": [
      { "_id": "65f1a2b3c4d5e6f708192a3d", "name": "Add 10 XP", "type": "platform-action", "order": 1, "continueOnFailure": false, "retryOnFailure": false, "options": { "action": "post-user-fields" } },
      { "_id": "65f1a2b3c4d5e6f708192a3c", "name": "Read member XP", "type": "platform-action", "order": 2, "continueOnFailure": false, "retryOnFailure": false, "options": { "action": "get-user-fields" } }
    ],
    "revision": "68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501",
    "redactedPaths": []
  }
}

curl --request POST \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows/<workflowId>/nodes/<nodeId>/move' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "after": "trigger"
  }'

Response#

HTTP 200 with the whole workflow and its new revision. The response is the readback: nodes is the new main-line order with order renumbered from 1, and branch members keep their relative order inside their branch.

Order decides what a step can read. After a move, run POST /{workflowId}/validate: a step that now runs before the step it reads reports REFERENCE_NOT_UPSTREAM.

data#object

A workflow with its trigger, its steps in canvas order and its revision.

Eg{ ... }

_id#string

Workflow identifier.

Eg"65f1a2b3c4d5e6f708192a3b"

communityId#string

Community the workflow belongs to.

Eg"65f1a2b3c4d5e6f708192a50"

name#string

Workflow name.

Eg"VIP bonus"

status#string

draft, deployed or undeployed.

Eg"draft"

outgoingWebhookUrl#string

Failure webhook URL, when one is set.

RuleNullable

Egnull

createdAt#string

Creation time.

Eg"2026-10-24T09:15:00.000Z"

updatedAt#string

Last authored change.

Eg"2026-10-24T09:20:11.000Z"

trigger#object

The trigger, or null when the workflow has none.

RuleNullable

Eg{ ... }

_id#string

Trigger identifier. Use it as the source of a reference.

Eg"65f1a2b3c4d5e6f708192a41"

name#string

Display name.

Eg"Trade bonus trigger"

type#string

Trigger type.

Eg"webhook"

status#string

Trigger lifecycle state, for example idle.

Eg"idle"

options#object

Trigger options. A webhook key is shown only in the response that created it.

RuleNullable

Eg{ ... }

nodes#object[]

Main-line steps in canvas order, routers carrying their branches.

Eg[ ... ]

_id#string

Step identifier.

Eg"65f1a2b3c4d5e6f708192a3c"

name#string

Step name.

Eg"Read member XP"

type#string

Step type.

Eg"platform-action"

order#integer

Position on the main line, from 1.

Eg1

continueOnFailure#boolean

Whether a failure stops the run.

Egfalse

retryOnFailure#boolean

Whether the step is retried on failure.

Egfalse

options#object

Stored step options, with every credential replaced by ["__REDACTED__"].

RuleNullable

Eg{ ... }

status#string

Last run state of the step, when one exists.

Eg"success"

nestedNodes#object[]

Present on a router: each branch carries its own workflowNodeIds and nestedNodes.

revision#string

64 hexadecimal characters. Send it back as If-Match; it also arrives as the ETag header.

Eg"162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c"

redactedPaths#string[]

Every location where a credential was replaced by ["__REDACTED__"].

Eg[]

{
  "data": {
    "_id": "65f1a2b3c4d5e6f708192a3b",
    "communityId": "65f1a2b3c4d5e6f708192a50",
    "name": "VIP bonus",
    "status": "draft",
    "outgoingWebhookUrl": null,
    "createdAt": "2026-10-24T09:15:00.000Z",
    "updatedAt": "2026-10-24T09:20:11.000Z",
    "trigger": {
      "_id": "65f1a2b3c4d5e6f708192a41",
      "name": "Trade bonus trigger",
      "type": "webhook",
      "status": "idle",
      "options": {
        "tokenExchangeEnabled": false,
        "apiKey": {
          "enabled": false
        },
        "aesKey": {
          "enabled": false
        }
      }
    },
    "nodes": [
      {
        "_id": "65f1a2b3c4d5e6f708192a3c",
        "name": "Read member XP",
        "type": "platform-action",
        "order": 1,
        "continueOnFailure": false,
        "retryOnFailure": false,
        "options": {
          "action": "get-user-fields",
          "selectUser": {
            "type": "email",
            "value": ["{{65f1a2b3c4d5e6f708192a41.email}}"]
          },
          "fields": [
            {
              "label": "Total XP",
              "field": "total_xp"
            }
          ]
        }
      }
    ],
    "revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
    "redactedPaths": []
  }
}

Errors#

Fix the request06

400VALIDATION_FAILEDFix the request

The step or the after target is not on the main line, or the body is missing after. Use main-line step ids only.

401AUTHENTICATION_REQUIREDFix the request

No key, or an unknown key. Send a valid key.

401API_KEY_REQUIREDFix the request

A valid admin session was used, because this API accepts community API keys only. Use a community API key.

403API_KEY_PERMISSION_DENIEDFix the request

No workflowBuilder. Grant the permission.

413VALIDATION_FAILEDFix the request

The request body is too large to read. Nothing was written. Send a smaller body; a large import is better split into a create plus step writes.

415UNSUPPORTED_MEDIA_TYPEFix the request

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

Fix the data03

404NODE_NOT_FOUNDFix the data

The step is not part of this workflow. Read the workflow for its step ids.

409VERSION_CONFLICTFix the data

You sent an If-Match that is not the current revision. meta.currentRevision carries the live value. Re-read and resend.

409WORKFLOW_LOCKEDFix the data

Another write to this workflow held the lock for too long, and this write was not applied. Re-read and retry.

Retry with backoff03

429RATE_LIMITEDRetry with backoff

The community's API rate limit was reached. Wait for the window to reset, then retry.

500INTERNAL_ERRORRetry with backoff

Unexpected failure. Re-read the workflow before retrying.

503LOCK_UNAVAILABLERetry with backoff

The write lock store did not answer, so nothing was written. Retry shortly.

Retries

Send If-Match if a duplicate move matters: a retry with the same revision is refused with 409 VERSION_CONFLICT after the first attempt lands. Without the header a retry applies again, and the second move is a no-op because the step is already in place. Moving a step to the position it already has is a successful no-op that still changes nothing except updatedAt; the revision does not change in that case.

{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_FAILED",
    "errors": [
      {
        "path": "params.workflowId",
        "message": "Id must be a 24 character hex string"
      }
    ],
    "requestId": "3f4d0e8b-7a6c-4f1e-9b2d-5a7c8e1f0a3b"
  },
  "message": "API request rejected error.",
  "detail": "The request body is not valid.",
  "solution": "Read error detail and try again."
}

Next step#

Duplicate a stepPOST/v1/workflow-builder/data-workflows/{workflowId}/nodes/{nodeId}/duplicate

Reorder a main-line step

01Authentication#

02Behaviour#

03Request#

Path parameters#

Headers#

Body#

Watch for

04Response#

05Errors#

Retries

06Next step#

Authentication#

Behaviour#

Request#

Response#

Errors#

Next step#