Undeploy a workflow

POST /{workflowId}/undeploy needs workflowBuilder.

What this endpoint does

Takes a workflow out of service without deleting anything. Steps, trigger configuration, credentials and run history all stay, so the workflow can be inspected, fixed and deployed again.

After an undeploy the trigger no longer starts runs.

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 be refused instead of overwriting a concurrent change, or omit it for last-write-wins.

Failure	Meaning	Recovery
`404 WORKFLOW_NOT_FOUND`	Unknown id, or another community's workflow	Use an id from this community.
`409 VERSION_CONFLICT`	You sent an `If-Match` that is not the current revision	Re-read and undeploy again.

Complete examples

{
  "data": {
    "_id": "65f1a2b3c4d5e6f708192a3b",
    "communityId": "65f1a2b3c4d5e6f708192a50",
    "name": "VIP bonus",
    "status": "undeployed",
    "outgoingWebhookUrl": null,
    "createdAt": "2026-10-24T09:15:00.000Z",
    "updatedAt": "2026-10-24T13:30:08.000Z",
    "trigger": { "_id": "65f1a2b3c4d5e6f708192a41", "name": "Trade bonus trigger", "type": "event-ingest", "status": "idle", "options": { "batchIdPath": "metadata.batch_id", "recordIdPaths": ["trade_id"] } },
    "nodes": [],
    "revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
    "redactedPaths": []
  }
}

Success and readback

HTTP 200 with the workflow and status: "undeployed", plus the new revision. Read back with GET /{workflowId}: the status must be undeployed, the steps and trigger configuration must be unchanged, and GET /{workflowId}/runs must still return the earlier runs.

The negative check is what settles it: an event sent to the trigger after the undeploy must not create a run.

Errors and recovery

Status and code	When	Recovery
`400 VALIDATION_FAILED`	The id is malformed	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	Use an id from this community.
`409 VERSION_CONFLICT`	You sent an `If-Match` that is not the current revision. `meta.currentRevision` carries the live value	Re-read and retry.

Retry safety

Undeploying an undeployed workflow is a no-op that returns the same status. It is safe to retry after a timeout: check the status first, and re-read the revision if the first call landed.

Gotchas

Undeploy is not a pause button for one sender. Anything that can still reach the trigger gets no run, but the sender is not notified, so stop the sender too.

Runs already in flight are not cancelled. Read the runs list after the undeploy to see what finished.

Undeploying does not change a webhook key or an ingest path, so the same credentials keep working after a redeploy.

Undeploy is optional before a delete: a deployed workflow can be deleted directly. Undeploying first is the gentler option when the intent is to stop runs before deciding.

workflowBuilder covers undeploy like every other route: there is no separate deployment permission to grant or withhold.

Next steps

PATCH /{workflowId}/nodes/{nodeId} to fix what you took it down for, then POST /{workflowId}/deploy again.

POST /{workflowId}/test with mode: "dry-run" for a check of the fixed workflow.

POST /{workflowId}/deploy to put it back.

Responses

🟢200200 Success

application/json

The workflow is out of service. Steps, trigger configuration and run history are kept.

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

{ "data": { "_id": "65f1a2b3c4d5e6f708192a3b", "communityId": "65f1a2b3c4d5e6f708192a50", "name": "VIP bonus", "status": "undeployed", "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": "68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501", "redactedPaths": [] } }

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request