API reference / Workflow Builder

Delete a workflow

Deletes one workflow together with its trigger, its steps and its run history.

Last updated 28 Oct 2026API v1

Method: DELETE
Path: https://api.returning.ai/v1/workflow-builder/data-workflows/{workflowId}
Permission: workflowBuilder
Retries: A retry after an ambiguous failure is safe in the sense that a second delete of a missing workflow answers 404 rather than deleting something else.

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 and a stale value is refused with 409 VERSION_CONFLICT instead of deleting a workflow someone else has changed since; omit it and the delete applies as the last write. Deleting a deployed workflow needs no extra header: the delete applies immediately.

Deleting is a client-visible, irreversible change. Take an export first if the workflow should be recoverable.

Failure	Meaning	Recovery
`409 VERSION_CONFLICT`	Someone changed or already deleted it since your read	Re-read; if it is gone, the delete is effectively done.

Behaviour#

It is irreversible: there is no restore route and no recycle bin.

A deployed workflow can be deleted like any other, in one call, with its trigger, steps and run history. Because that takes a live workflow out of service and leaves nothing to read back, POST /{workflowId}/undeploy first when the intent is to stop it rather than remove it.

Request#

Path parameters#

workflowId#stringREQUIRED

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

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

Eg65f1a2b3c4d5e6f708192a3b

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 step, a branch or a whole workflow cannot be undone. Export first.
A delete does not need an undeploy first, and it does not need a confirmation header. A deployed workflow is removed in one call, so the export and the second read in this page are the only protection there is.
Run history goes with the workflow. Export anything you need to keep from GET /{workflowId}/runs before deleting.
Deleting does not revoke a webhook key that was stored elsewhere. The key becomes useless once the trigger is gone, but stop senders as well.
A delete is logged as one audit line with the workflow id, the operation and the revision before it. The body is never logged.

More examples and details

Export first when the definition matters:

BASH

curl --request GET \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/export" \
  --header "Authorization: Bearer <API_KEY>" \
  --output vip-bonus.workflow.json

Then delete:

BASH

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

JSON

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

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

Response#

HTTP 200 with data.deleted: true. There is nothing left to read back on the workflow itself, so prove the delete with the list: GET / must no longer contain that _id, and GET /{workflowId} must answer 404 WORKFLOW_NOT_FOUND. Runs of the workflow are removed with it, so GET /{workflowId}/runs also answers 404.

The response carries no revision: a deleted workflow has none.

data#object

Deletion result.

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

id#string

Identifier of the deleted object.

Eg"65f1a2b3c4d5e6f708192a3b"

deleted#boolean

Always true on a successful delete.

Egtrue

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

Errors#

Fix the request04

400VALIDATION_FAILEDFix the request

The id is not 24 hexadecimal characters. Use the id 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

404WORKFLOW_NOT_FOUNDFix the data

Unknown id, or another community's workflow. Nothing to delete; confirm with the list.

409VERSION_CONFLICTFix the data

You sent an If-Match that is not the current revision. Re-read; retry only if the workflow still exists.

409WORKFLOW_LOCKEDFix the data

Another write to this workflow is in progress. Re-read; retry only if the workflow still exists.

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 before retrying: a partial cascade is possible on a database failure, and the workflow may already be gone.

503LOCK_UNAVAILABLERetry with backoff

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

Retries

A retry after an ambiguous failure is safe in the sense that a second delete of a missing workflow answers 404 rather than deleting something else. Do not switch to a new id to "make the delete work": confirm with GET / which id still exists. The cascade is not transactional. A failure part way through can leave the workflow row removed while a run record briefly remains; the records are scoped to the deleted id and are not reachable through any read.

{
  "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 workflowPOST/v1/workflow-builder/data-workflows/{workflowId}/duplicate

Delete a workflow

01Authentication#

02Behaviour#

03Request#