Publish the draft as the next version (tenant:flows:write for own personal flows, tenant:flows:admin for tenant flows, the owning module's manage for scoped flows)
POST /api/flows/v1/flows/{id}/publish
Module: Flows · operationId: publishFlow · Tag: Flows · Auth: access token (Authorization: Bearer <accessToken>)
The draft must be valid (422 invalid_definition with details.diagnostics) and differ from the published
version (409 no_changes). A mail node's mandatory and mailChannel are reserved for tenant flows without
scope: in a personal or scoped flow each is the finding mail_option_not_allowed (params.option, on the
node's field), shown on the draft and refused here like any error. HR confirms that the owner holds at least one permission of every action and event
the flow uses (422 permission_missing with details.groups) and, for a tenant flow – a scoped flow is one –,
that you hold every permission of its service account (403 forbidden_grant). A token that carries only a subset of
the person's or account's permissions (API key, OAuth client, the assistant, a flow, the mobile app) must itself hold every
permission the version would act with (403 forbidden_grant, details.missing). The confirmed permissions are stored with the version
and are exactly what its runs act with. Publishing enables the flow and arms its triggers: a new webhook (or one
that became hmac) gets its address, token and signing secret in webhooks – shown only in this answer
(POST …/triggers/{trigger}/rotate issues new ones).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes |
Request body
application/json (required)
version(integer, required): The draft's version you reviewednote(string): Note stored with the version (max length 500)
Example:
{
"note": "Empfänger auf die Systemadministration umgestellt",
"version": 6
}
Responses
- 201 The new version (
application/json) - 400 Invalid input (
invalid);fieldnames the first invalid field,details.fieldsevery one. (application/json) - 401 Missing, invalid or expired token (no body).
- 403 The token lacks the permission or has no active tenant (
forbidden). Also:person_required(a service-account key on personal flows or the task inbox),live_test_forbidden,forbidden_grant,starter_excluded. (application/json) - 404 The record does not exist in the token's tenant – or it belongs to a scope the caller may not view (a scoped flow stays hidden). (
application/json) - 409 The state does not allow it: version_conflict (reload), no_changes, archived, key_taken, flow_disabled, flow_tripped, task_closed, run_finished. (
application/json) - 422 invalid_definition (details.diagnostics), permission_missing (details.groups), owner_inactive, owner_not_found, not_published, key_changed, not_webhook, filter_failed, unknown_trigger, no_manual_trigger. (
application/json) - 503 A dependency is not available:
scope_unavailable(the module that owns a flow's scope did not answer who may see and manage it – nothing of a scoped flow is shown or changed),identity_unavailable(HR),ai_unavailable,ai_failed. (application/json)
Fields of the 201 answer:
createdAt(string (date-time)): When it was publishedcreatedBy(string): E-mail of who published itnote(string): Note given at publishnumber(integer): Version number, counting from 1permissions(array of string): What the runs of this version act withwebhooks(array of WebhookCredential): Only in the answer of the publish that created thempath(string, required): The address on the portal origin: /api/flows/v1/hooks/{token}token(string, required): The webhook token (the credential in the path)trigger(string, required): The trigger's idsecret(string): auth hmac: signs the body, header X-Flows-Signature: sha256=<hex of HMAC-SHA256(secret, body)>
yaml(string): Only when one version is read
Example 201 answer:
{
"createdAt": "2026-11-12T14:03:27Z",
"createdBy": "sophie.huber@muster-it.example",
"note": "Empfänger auf die Systemadministration umgestellt",
"number": 2,
"permissions": [
"desk:read"
],
"yaml": "schemaVersion: 1\nkey: kritische-tickets-zusammenfassen\nname: Kritische Tickets zusammenfassen\ntriggers:\n - { id: neues_ticket, kind: event, event: desk.item.created, filter: \"trigger.data.priority in ['hoch', 'kritisch']\" }\nnodes:\n ticket:\n kind: action\n name: Ticket lesen\n action: desk.item.get\n params: { ref: \"{{ trigger.data.itemId }}\" }\n info:\n kind: mail\n name: Systemadministration informieren\n to: [\"person:jonas.bauer@muster-it.example\"]\n subject: \"Kritisches Ticket {{ trigger.data.number }}\"\n text: \"{{ nodes.ticket.output.title }}\"\nedges:\n - neues_ticket -\u003e ticket\n - ticket -\u003e info\n"
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/publish' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"note":"Empfänger auf die Systemadministration umgestellt","version":6}'