ConnectCloud Developers

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:

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

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

View as Markdown · Interactive reference · OpenAPI