Delete a step

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

What this endpoint does

Removes one step from a workflow. Deleting a router removes its branches and the steps inside them, and clears the branch pointers in one operation.

The delete is permanent, and references from later steps to the deleted step become unresolved until they are changed.

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

Delete a step, then check what now refers to nothing:

{
  "data": {
    "id": "65f1a2b3c4d5e6f708192a3c",
    "deleted": true
  }
}

Success and readback

HTTP 200 with data.deleted: true. There is no revision in this response, so the readback is a GET /{workflowId}: it returns the new revision, shows the step is absent, and shows its branch membership is gone from any router that listed it.

Run POST /{workflowId}/validate after the delete: a step that read the deleted step now reports REFERENCE_UNRESOLVED, and a router branch that listed it reports NODE_NOT_IN_WORKFLOW.

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	Confirm with `GET /{workflowId}`.
`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 step answers 404 NODE_NOT_FOUND, which is the same end state. Do not create a replacement step to "make the retry work"; read the workflow instead.

Gotchas

Deleting a router deletes every step in its branches. Those steps are not reattached anywhere.

Deleting a step does not rewrite references in other steps. POST /{workflowId}/validate reports the dangling references as warnings and deploy still proceeds, so fix them before the next run.

Run history is not rewritten. An old run still shows the deleted step's result under its old id.

A delete cannot be undone. Export the workflow first if the step is worth recovering.

Next steps

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

PATCH /{workflowId}/nodes/{nodeId} on the affected steps to point them elsewhere.

GET /{workflowId} for the new revision.

Responses

🟢200200 Success

application/json

The step was removed. A router takes its branch members with it.

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 DELETE 'https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes/65f1a2b3c4d5e6f708192a3c' \ --header 'Authorization: Bearer <API_KEY>' \ --header 'If-Match: 162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c'

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request