API reference / Workflow Builder

Undeploy a workflow

Takes a workflow out of service without deleting anything.

Last updated 28 Oct 2026API v1

Method: POST
Path: https://api.returning.ai/v1/workflow-builder/data-workflows/{workflowId}/undeploy
Permission: workflowBuilder
Retries: Undeploying an undeployed workflow is a no-op that returns the same status.

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

Behaviour#

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.

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

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.

More examples and details

BASH

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

JSON

{
  "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": []
  }
}

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

Response#

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.

data#object

A workflow with its trigger, its steps in canvas order and its revision.

Eg{ ... }

_id#string

Workflow identifier.

Eg"65f1a2b3c4d5e6f708192a3b"

communityId#string

Community the workflow belongs to.

Eg"65f1a2b3c4d5e6f708192a50"

name#string

Workflow name.

Eg"VIP bonus"

status#string

draft, deployed or undeployed.

Eg"undeployed"

outgoingWebhookUrl#string

Failure webhook URL, when one is set.

RuleNullable

Egnull

createdAt#string

Creation time.

Eg"2026-10-24T09:15:00.000Z"

updatedAt#string

Last authored change.

Eg"2026-10-24T09:20:11.000Z"

trigger#object

The trigger, or null when the workflow has none.

RuleNullable

Eg{ ... }

_id#string

Trigger identifier. Use it as the source of a reference.

Eg"65f1a2b3c4d5e6f708192a41"

name#string

Display name.

Eg"Trade bonus trigger"

type#string

Trigger type.

Eg"webhook"

status#string

Trigger lifecycle state, for example idle.

Eg"idle"

options#object

Trigger options. A webhook key is shown only in the response that created it.

RuleNullable

Eg{ ... }

nodes#object[]

Main-line steps in canvas order, routers carrying their branches.

Eg[ ... ]

_id#string

Step identifier.

Eg"65f1a2b3c4d5e6f708192a3c"

name#string

Step name.

Eg"Read member XP"

type#string

Step type.

Eg"platform-action"

order#integer

Position on the main line, from 1.

Eg1

continueOnFailure#boolean

Whether a failure stops the run.

Egfalse

retryOnFailure#boolean

Whether the step is retried on failure.

Egfalse

options#object

Stored step options, with every credential replaced by ["__REDACTED__"].

RuleNullable

Eg{ ... }

status#string

Last run state of the step, when one exists.

Eg"success"

nestedNodes#object[]

Present on a router: each branch carries its own workflowNodeIds and nestedNodes.

revision#string

64 hexadecimal characters. Send it back as If-Match; it also arrives as the ETag header.

Eg"68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501"

redactedPaths#string[]

Every location where a credential was replaced by ["__REDACTED__"].

Eg[]

{
  "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": []
  }
}

Errors#

Fix the request04

400VALIDATION_FAILEDFix the request

The id is malformed. 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. Use an id from this community.

409VERSION_CONFLICTFix the data

You sent an If-Match that is not the current revision. meta.currentRevision carries the live value. Re-read and retry.

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 status before retrying.

503LOCK_UNAVAILABLERetry with backoff

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

Retries

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.

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

List the runs of a workflowGET/v1/workflow-builder/data-workflows/{workflowId}/runs

Undeploy a workflow

01Authentication#

02Behaviour#

03Request#

Path parameters#

Headers#

Watch for

04Response#

05Errors#

Retries

06Next step#

Authentication#

Behaviour#

Request#

Response#

Errors#

Next step#