API reference / Workflow Builder

Delete a step

Removes one step from a workflow.

Last updated 28 Oct 2026API v1

Method: DELETE
Path: https://api.returning.ai/v1/workflow-builder/data-workflows/{workflowId}/nodes/{nodeId}
Permission: workflowBuilder
Retries: A second delete of the same step answers 404 NODE_NOT_FOUND, which is the same end state.

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

Behaviour#

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.

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

Watch for

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.

More examples and details

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

BASH

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

JSON

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

curl --request DELETE \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows/<workflowId>/nodes/<nodeId>' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

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.

data#object

Deletion result.

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

id#string

Identifier of the deleted object.

Eg"65f1a2b3c4d5e6f708192a3c"

deleted#boolean

Always true on a successful delete.

Egtrue

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

Errors#

Fix the request04

400VALIDATION_FAILEDFix the request

An id is not 24 hexadecimal characters. Use the ids exactly as returned.

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.

Fix the data03

404NODE_NOT_FOUNDFix the data

The step is not part of this workflow. Confirm with GET /{workflowId}.

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: the step may already be gone.

503LOCK_UNAVAILABLERetry with backoff

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

Retries

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.

{
  "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#

Reorder a main-line stepPOST/v1/workflow-builder/data-workflows/{workflowId}/nodes/{nodeId}/move

Delete a step

01Authentication#

02Behaviour#

03Request#