Publish the current draft and make the workflow live
workflow:publishSnapshots the DRAFT (workflow.definition) into a new immutable version and sets status to active. Production traffic executes the SNAPSHOT, never the draft — so editing a live workflow changes nothing until you publish again.
What a caller must know:
- This is the endpoint that mints the webhook token. If the workflow's
triggerTypeiswebhookand it has no token yet, publishing generates one and the response carries it aswebhookToken. That token is the workflow's public production door:POST /api/webhooks/{webhookToken}, which is UNAUTHENTICATED — the unguessable URL is the credential. Anyone holding it can start production runs. To revoke it, callPOST /api/workflows/{id}/webhook/rotate. - Publishing an UNCHANGED definition mints no new version (
CreateIfChanged); it still returns 200 and the samelatestVersionId. Publish is therefore safe to repeat and carries noIdempotency-Key. - Publishing is required before
POST /api/workflows/{id}/run?environment=productionwill work. - Re-publishing an already-active workflow first tears down any self-registered external webhook (Stripe/Telegram-style trigger pieces) and re-registers it. That is best-effort and never fails the publish.
- No request body is read.
The publish gate refuses (422) on the FIRST blocking validation diagnostic — the same validator POST /api/workflows/validate reports, so what one reports the other refuses. It also refuses an unparseable cron schedule, approval links nothing waits on, an errorWorkflowId that cannot fire, and an error/run-finished trigger watching a workflow that cannot be watched. The message names the fault and, where there is a closed set, the legal alternatives.
Authorization
bearerAuth An API token: Authorization: Bearer grt_…. Mint one in the app under Settings → Workspace → API tokens; the raw value is shown once. Scopes confine the token — see x-permission on each operation.
In: header
Path Parameters
Workflow id (UUID). A non-UUID value is a 400, not a 404.
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/workflows/497f6eca-6276-4993-bfeb-53cbbbba6f08/publish"{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "description": "string", "definition": { "schemaVersion": 2, "trigger": { "name": "string", "displayName": "string", "type": "manual", "pieceId": "string", "pieceVersion": "string", "actionId": "string", "config": {}, "connectionId": "string", "valid": true, "nextAction": { "name": "string", "displayName": "string", "type": "PIECE", "pieceId": "string", "pieceVersion": "string", "actionId": "string", "config": {}, "connectionId": "string", "valid": true, "skip": true, "nextAction": {}, "branches": [ { "name": "string", "conditions": [ [ { "field": "string", "operator": "string", "value": null } ] ], "firstAction": {} } ], "firstLoopAction": {}, "onErrorAction": {} } }, "settings": { "timeoutSeconds": 0, "errorWorkflowId": "string", "concurrencyLimit": 0, "maintenanceMode": true, "autoPublishFixes": true }, "variables": {}, "annotations": null, "pinnedData": {} }, "status": "draft", "triggerType": "manual", "cronExpression": "string", "webhookToken": "string", "latestVersionId": "750445c5-7ad9-40bd-a593-bb37d7d846db", "definitionRev": 0, "hasUnpublishedChanges": true, "folderId": "5b6379a4-2a6c-4085-b184-45838a3b8e7e", "tags": [ "string" ], "testPayloads": {}, "pinnedData": {}, "workspaceId": "ef0efa32-d1c1-43d4-a5e2-fe7b4f00403c", "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa", "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" }}