## 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 reviewed
- `note` (string): Note stored with the version (max length 500)

Example:

```json
{
  "note": "Empfänger auf die Systemadministration umgestellt",
  "version": 6
}
```

### Responses

- **201** The new version (`application/json`)
- **400** Invalid input (`invalid`); `field` names the first invalid field, `details.fields` every 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 published
- `createdBy` (string): E-mail of who published it
- `note` (string): Note given at publish
- `number` (integer): Version number, counting from 1
- `permissions` (array of string): What the runs of this version act with
- `webhooks` (array of WebhookCredential): Only in the answer of the publish that created them
  - `path` (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 id
  - `secret` (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:

```json
{
  "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

```bash
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}'
```
