Deploy a workflow

01Authentication#

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, omit it and the deploy applies as the last write. Deploying a workflow that is already deployed is allowed, and needs no extra header.

There is no separate deploy permission: the one workflowBuilder permission covers building, testing, deploying and reading. If you want a workflow to be reviewable before it runs, that has to be a policy on your side, or a copy of the workflow deployed while the original stays undeployed.

02Behaviour#

03Request#

Path parameters#

Headers#

Watch for

• Deploy does not refuse a workflow with no trigger. It deploys, status reads deployed, and nothing runs until PUT /{workflowId}/trigger sets one; the response's warnings carry TRIGGER_REQUIRED.
• Deploy rebuilds the workflow's step order from the stored steps: main line by order, then each router's branch members. The order a client last sent is not trusted.
• A deployed workflow accepts every edit, including a delete, and the change applies to the next run immediately. Copy, edit the copy, dry-run it, then deploy the copy if you want a reviewable change.
• No validation finding refuses a deploy: a router that uses OR or WHERE condition groups, a template whose step id is not in the workflow, retryOnFailure on a router that pays, an empty imported credential, POST_LOGIC_REQUIRED, NODE_LISTED_TWICE or MISSING_SECRET all arrive as warnings and the workflow goes live. The warnings are the whole safety net, so read them.
• Because the validator reuses the run path's own reference and operator rules, a warning names exactly what a run will mishandle: a condition the platform evaluates as always true, a reference that resolves to nothing, a retry that repeats a payout.
• A Code step deploys like any other step. Its source runs in the platform sandbox on every run, so dry-run it first if you have not run that source here before.
• Deploying does not send a test event and does not prove the trigger is reachable from outside. Fire it for real.
• A webhook key cannot be changed by a deploy or by a PUT that sends a new value. Getting a different key means replacing the trigger's webhook type, which is a trigger change, not a deploy.

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

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

{
  "data": {
    "_id": "65f1a2b3c4d5e6f708192a3b",
    "communityId": "65f1a2b3c4d5e6f708192a50",
    "name": "VIP bonus",
    "status": "deployed",
    "outgoingWebhookUrl": null,
    "createdAt": "2026-10-24T09:15:00.000Z",
    "updatedAt": "2026-10-24T13:02:41.000Z",
    "trigger": { "_id": "65f1a2b3c4d5e6f708192a41", "name": "Trades", "type": "event-ingest", "status": "idle", "options": { "batchIdPath": "metadata.batch_id", "recordIdPaths": ["trade_id"] } },
    "nodes": [],
    "revision": "68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501",
    "redactedPaths": [],
    "warnings": [
      { "nodeId": "65f1a2b3c4d5e6f708192a3e", "path": "options.branches[0].conditions[0].operator", "code": "ROUTER_OPERATOR_UNSAFE", "message": "The runtime treats OR and WHERE condition groups as always true." },
      { "nodeId": "65f1a2b3c4d5e6f708192a3d", "path": "options.fields[0].value", "code": "REFERENCE_MAY_BE_UNSET", "message": "This reads a branch step that may not run; the value can be unset." }
    ]
  }
}

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

04Response#

HTTP 200 with the workflow, status: "deployed" and the new revision in the body and the ETag header. The trigger reads idle, which is the armed state. The body also carries warnings, the same advisory findings POST /{workflowId}/validate returns, so an agent that skipped validate still sees them. Read them, because nothing else will stop the workflow from running in a shape the platform warns about.

Read back with GET /{workflowId}: status must be deployed, and the trigger must be the type you expect. Then prove the workflow runs: fire the trigger with a synthetic event and read the run with GET /{workflowId}/runs. A deploy alone proves configuration, not execution.

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

05Errors#

{
  "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."
}

06Next step#