Delete a workflow

DELETE /{workflowId} needs workflowBuilder.

What this endpoint does

Deletes one workflow together with its trigger, its steps and its run history. 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.

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 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.

Complete examples

Export first when the definition matters:

Then delete:

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

Success and readback

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.

Errors and recovery

Status and code	When	Recovery
`400 VALIDATION_FAILED`	The id is not 24 hexadecimal characters	Use the id 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 WORKFLOW_NOT_FOUND`	Unknown id, or another community's workflow	Nothing to delete; confirm with the list.
`409 VERSION_CONFLICT`	You sent an `If-Match` that is not the current revision	Re-read; retry only if the workflow still exists.
`409 WORKFLOW_LOCKED`	Another write to this workflow is in progress	Re-read; retry only if the workflow still exists.
`429 RATE_LIMITED`	The community's API rate limit was reached	Wait for the window to reset, then retry.
`500 INTERNAL_ERROR`	Unexpected failure	Re-read before retrying: a partial cascade is possible on a database failure, and the workflow may already be gone.
`503 LOCK_UNAVAILABLE`	The write lock store did not answer, so nothing was written	Retry shortly.

Retry safety

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.

Gotchas

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.

Next steps

GET / to confirm the workflow is gone.

POST / to recreate it from an export if it was deleted by mistake.

POST /{workflowId}/undeploy first, when the target is still deployed.

Responses

🟢200200 Success

application/json

The workflow, its trigger, its steps and its run history were removed.

Bodyapplication/json

🟠400400 VALIDATION_FAILED

🟠401401 AUTHENTICATION_REQUIRED / API_KEY_REQUIRED

🟠403403 API_KEY_PERMISSION_DENIED

🟠404404 WORKFLOW_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' \ --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