# ConnectCloud Flows API (v1.0.0)

Automation: flows as YAML graphs of triggers (events, schedules, manual starts, webhooks) and nodes (module actions, conditions, human tasks, waits, loops, sub-flows, mail, AI); drafts, validation, test runs, publishing, runs with their node history and the task inbox.

Base URLs:

- Production: `https://api.mbcom.cloud`
- Staging: `https://api.mbcom.cloud`
- Sandbox: `https://developers.mbcom.cloud/sandbox/flows`

The flows module automates the platform: a **flow** is a graph of nodes (triggers, module actions, conditions,
human tasks, waits, loops, sub-flows, mail and AI steps) stored as YAML. Flows react to events of every module,
to schedules, to manual starts and to inbound webhooks, and act in every module through the operations the modules
offer to flows (`x-flows` in their API descriptions).

All paths in this document are full paths; the server URL is the origin.

## Events
flows writes its events (`flows.flow.created|updated|published|archived|tripped`,
`flows.run.started|succeeded|failed|cancelled`, `flows.task.created|completed|reassigned`; ids and states only, never run
data; a `flows.flow.*` event of a scoped flow names its `scope`) to an outbox that ConnectCloud services read. API
clients follow runs with `GET /api/flows/v1/runs`.

## Who may do what
A **personal** flow belongs to the person who created it (`tenant:flows:write`) and acts with their permissions;
a **tenant** flow needs `tenant:flows:admin` and acts as the service account it names. Service-account API keys
own no personal flows (`403 person_required`). The task inbox (`/api/flows/v1/tasks`) belongs to people: sign-in
sessions and personal API keys pass, service-account keys get `403 person_required`. The webhook receiver
`POST /api/flows/v1/hooks/{token}` needs no token at all – the webhook token in the path is the credential.

## Scoped flows
A flow may belong to something of a module: its `scope` is `desk:space:<id>` (a desk space) or
`forge:project:<id>` (a forge project). A scoped flow is a tenant flow – it acts as its service account, and
publishing checks the account's permissions as for every tenant flow – but who may see and manage it is answered by
the module that owns the scope, live at every request, not by `tenant:flows:admin`:

- **see** the flow, its draft, versions, triggers and runs: whoever the module lets *view* the scope (and holds any
  flows permission);
- **create, change, save and publish the draft, enable, archive, restore, rotate a webhook, start, test and cancel
  runs**: whoever the module lets *manage* the scope (and holds `tenant:flows:write` or `tenant:flows:admin`). A
  flows admin without that answer changes nothing, a maintainer of the space or project with `tenant:flows:write`
  does;
- a task of its runs is read by its assignees and by who manages the scope.

A caller who may not view the scope gets `404` on every route of the flow (it stays hidden), one who views but may
not manage it `403 forbidden`. When the owning module cannot answer, every such route answers
`503 scope_unavailable` – nothing of a scoped flow is shown or changed then. Service-account API keys have no person
the module could look up: scoped flows are hidden from them (`404`). Scoped flows are listed only with
`GET /api/flows/v1/flows?scope=…`, never in the plain list; their runs only with `flowId`. A scoped flow calls tenant
flows without scope and flows of its own scope as sub-flows; a tenant flow without scope never calls a scoped one.


## Authentication
Send an access token as `Authorization: Bearer <accessToken>`. Get it by exchanging an API key at
`POST https://api.mbcom.cloud/api/hr/v1/auth/token`; it lives 15 minutes and carries the key's permissions.
The tenant is always the one of the token. Guide: https://developers.mbcom.cloud/guides/authentication

# Flows

## Check a flow definition without storing it (tenant:flows:read|write|admin)

`POST /api/flows/v1/validate`

Module: Flows · operationId: `validateFlowDefinition` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `yaml` (string, required): The definition (YAML, at most 256 KiB)

Example:

```json
{
  "yaml": "schemaVersion: 1\nkey: kritische-tickets-zusammenfassen\nname: Kritische Tickets zusammenfassen\ntriggers:\n  - { id: neues_ticket, kind: event, event: desk.item.created }\nnodes:\n  ticket:\n    kind: action\n    action: desk.item.get\n    params: { ref: \"{{ trigger.data.itemId }}\" }\nedges:\n  - neues_ticket -\u003e ticket\n"
}
```

### Responses

- **200** The findings (`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`)

Fields of the 200 answer:

- `diagnostics` (array of Diagnostic, required): Findings of the validator
  - `code` (string, required): Stable code, e.g. `unknown_port`, `invalid_assignee`, `mail_option_not_allowed` (a mail node sets `mandatory` or `mailChannel` in a personal or scoped flow)
  - `message` (string, required): Human-readable explanation
  - `severity` (string, required): Errors block publishing (one of `error`, `warning`)
  - `col` (integer): Column in the YAML (1-based)
  - `line` (integer): Line in the YAML (1-based)
  - `nodeId` (string): The node the finding is about
  - `params` (object): `mail_option_not_allowed`: `option` (`mandatory` or `mailChannel`)
  - `path` (string): Dotted path in the definition
- `permissions` (array of array of string, required): The any-of permission groups of the actions and events the flow uses
- `valid` (boolean, required): False when a finding has severity `error`
- `ports` (object): The output ports of every node that parsed, by node id (the builder's handles)

Example 200 answer:

```json
{
  "diagnostics": [
    {
      "code": "retry_unused",
      "col": 9,
      "line": 24,
      "message": "a mail node is never retried",
      "nodeId": "info",
      "path": "nodes.info.retry",
      "severity": "warning"
    }
  ],
  "permissions": [
    [
      "desk:read",
      "desk:write",
      "desk:admin"
    ]
  ],
  "ports": {
    "info": [
      "success",
      "error"
    ],
    "ticket": [
      "success",
      "error"
    ],
    "zusammenfassung": [
      "success",
      "error"
    ]
  },
  "valid": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/validate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"yaml":"schemaVersion: 1\nkey: kritische-tickets-zusammenfassen\nname: Kritische Tickets zusammenfassen\ntriggers:\n  - { id: neues_ticket, kind: event, event: desk.item.created }\nnodes:\n  ticket:\n    kind: action\n    action: desk.item.get\n    params: { ref: \"{{ trigger.data.itemId }}\" }\nedges:\n  - neues_ticket -\u003e ticket\n"}'
```

## List the flows the caller may see (tenant:flows:read|write|admin; with scope the owning module's view)

`GET /api/flows/v1/flows`

Module: Flows · operationId: `listFlows` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

Without `scope` the flows that belong to no scope: tenant flows for every flows permission; personal flows of
the caller (admins see every personal flow). Scoped flows are never in that list. With `scope` exactly the
flows of that scope, for whoever its module lets view it (`404` otherwise, `503 scope_unavailable` when the
module cannot answer); `canEdit` then tells whether the module lets the caller manage the scope.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `archived` | query | boolean |  | true lists the archived flows (default `false`) |
| `scope` | query | string |  | List the flows of this scope instead: `desk:space:<id>` or `forge:project:<id>` (the id a lower-case UUID); anything else is `400 invalid`, field `scope` (max length 160) |

### Responses

- **200** Flows (`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`)
- **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 200 answer:

- `items` (array of Flow, required): The flows
  - `archived` (boolean): Whether the flow is archived
  - `canEdit` (boolean): Whether the caller may change the draft and publish (a scoped flow: the owning module lets the caller manage the scope and the token holds tenant:flows:write or admin)
  - `createdAt` (string (date-time)): When the flow was created
  - `createdBy` (string): E-mail of the creator
  - `description` (string): Description from the definition
  - `enabled` (boolean): Whether the published version's triggers start runs
  - `id` (string (uuid)): Flow id
  - `key` (string): Unique per tenant; sub-flows call a flow by it
  - `name` (string): Display name
  - `owner` (string): `personal` (acts as its creator) or `tenant` (acts as its service account) (one of `personal`, `tenant`)
  - `ownerEmail` (string): Personal flows: the owner; tenant flows: who created it
  - `pausedReason` (string): Why runs stopped by themselves (owner_inactive, permission_lost, tripped)
  - `publishedNumber` (integer): The live version
  - `scope` (string): What the flow belongs to – `desk:space:<id>` or `forge:project:<id>`; absent for a tenant or personal flow. The owning module decides who sees and manages a scoped flow ("Scoped flows").
  - `serviceAccountId` (string (uuid)): Tenant flows: the account it acts as
  - `updatedAt` (string (date-time)): When the flow was changed last
  - `updatedBy` (string): E-mail of who changed the flow last
  - `version` (integer): Send it with changes
- `total` (integer): Number of items

Example 200 answer:

```json
{
  "items": [
    {
      "archived": false,
      "canEdit": true,
      "createdAt": "2026-10-21T09:20:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "description": "Bei jedem neuen Ticket mit hoher oder kritischer Priorität fasst die KI die Meldung zusammen und die Systemadministration bekommt eine Nachricht.",
      "enabled": true,
      "id": "6f2a9c4e-1b3d-4e5f-8a7b-9c0d1e2f3a4b",
      "key": "kritische-tickets-zusammenfassen",
      "name": "Kritische Tickets zusammenfassen",
      "owner": "personal",
      "ownerEmail": "sophie.huber@muster-it.example",
      "publishedNumber": 2,
      "updatedAt": "2026-11-12T14:03:27Z",
      "updatedBy": "sophie.huber@muster-it.example",
      "version": 5
    },
    {
      "archived": false,
      "canEdit": false,
      "createdAt": "2026-09-15T16:40:00Z",
      "createdBy": "thomas.pfeiffer@muster-it.example",
      "enabled": false,
      "id": "8b0d2f4a-6c8e-4a1b-9d3f-5a7c9e1b3d5f",
      "key": "tickets-nachts-pruefen",
      "name": "Offene Tickets nachts prüfen",
      "owner": "tenant",
      "ownerEmail": "thomas.pfeiffer@muster-it.example",
      "pausedReason": "permission_lost",
      "publishedNumber": 1,
      "serviceAccountId": "1c3e5a7b-9d2f-4b4a-8c6e-0a2b4c6d8e1f",
      "updatedAt": "2026-11-03T07:12:55Z",
      "updatedBy": "thomas.pfeiffer@muster-it.example",
      "version": 3
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/flows' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a flow (tenant:flows:write; tenant flows tenant:flows:admin; scoped flows tenant:flows:write and the owning module's manage)

`POST /api/flows/v1/flows`

Module: Flows · operationId: `createFlow` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

A personal flow belongs to the caller and acts with the caller's permissions; a tenant flow acts as the service
account it names and needs `tenant:flows:admin`. The draft starts from `yaml`, from a `template` (filled with
`params`) or a skeleton with a manual trigger. A template made for a kind of scope (`scope` in
`GET /api/flows/v1/templates`) needs a `scope` of that kind (`400 invalid`, field `scope`); a tenant-wide
template may be created into any scope. An inline template is an immediate automation of its module and never
a flow (`400 invalid`, field `template`).
With `scope` the flow belongs to a desk space or forge project: `owner` must be `tenant` and
`serviceAccountId` is required (`400 invalid`), and instead of `tenant:flows:admin` the module that owns the
scope must let the caller manage it – `404` when the caller may not view the scope, `403 forbidden` when they
view but may not manage it, `503 scope_unavailable` when the module cannot answer. The scope of a flow never
changes; keys stay unique per tenant.

### Request body

`application/json` (required)

- `name` (string, required): Display name (max length 200)
- `owner` (string, required): `personal` or `tenant` (one of `personal`, `tenant`)
- `key` (string): Lower case letters, digits and dashes; default derived from the name
- `params` (object): The values of the template's parameters by key (only with `template`: `400 invalid`, field `params`). A parameter left out takes its default; a wrong one is `400 invalid` with the field `params.<key>` – see `renderFlowTemplate`.
- `scope` (string): What the flow belongs to: `desk:space:<id>` or `forge:project:<id>` (the id a lower-case UUID). Only with `owner: tenant`; the owning module decides who sees and manages the flow. (max length 160)
- `serviceAccountId` (string (uuid)): Tenant flows: the service account the flow acts as
- `template` (string): The key of a durable template from `GET /api/flows/v1/templates`: the draft starts from its definition, filled with the new flow's key and name and the values of `params`. Not together with `yaml`, an unknown key and an inline template: `400 invalid`, field `template`. (max length 63)
- `yaml` (string): The first draft

Example:

```json
{
  "name": "Kritische Tickets melden",
  "owner": "personal",
  "params": {
    "priorities": [
      "hoch",
      "kritisch"
    ],
    "recipients": [
      "creator"
    ]
  },
  "template": "kritische-tickets-melden"
}
```

### Responses

- **201** Created (`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`)
- **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:

- `flow` (Flow)
  - `archived` (boolean): Whether the flow is archived
  - `canEdit` (boolean): Whether the caller may change the draft and publish (a scoped flow: the owning module lets the caller manage the scope and the token holds tenant:flows:write or admin)
  - `createdAt` (string (date-time)): When the flow was created
  - `createdBy` (string): E-mail of the creator
  - `description` (string): Description from the definition
  - `enabled` (boolean): Whether the published version's triggers start runs
  - `id` (string (uuid)): Flow id
  - `key` (string): Unique per tenant; sub-flows call a flow by it
  - `name` (string): Display name
  - `owner` (string): `personal` (acts as its creator) or `tenant` (acts as its service account) (one of `personal`, `tenant`)
  - `ownerEmail` (string): Personal flows: the owner; tenant flows: who created it
  - `pausedReason` (string): Why runs stopped by themselves (owner_inactive, permission_lost, tripped)
  - `publishedNumber` (integer): The live version
  - `scope` (string): What the flow belongs to – `desk:space:<id>` or `forge:project:<id>`; absent for a tenant or personal flow. The owning module decides who sees and manages a scoped flow ("Scoped flows").
  - `serviceAccountId` (string (uuid)): Tenant flows: the account it acts as
  - `updatedAt` (string (date-time)): When the flow was changed last
  - `updatedBy` (string): E-mail of who changed the flow last
  - `version` (integer): Send it with changes
- `validation` (Validation)
  - `diagnostics` (array of Diagnostic, required): Findings of the validator
    - `code` (string, required): Stable code, e.g. `unknown_port`, `invalid_assignee`, `mail_option_not_allowed` (a mail node sets `mandatory` or `mailChannel` in a personal or scoped flow)
    - `message` (string, required): Human-readable explanation
    - `severity` (string, required): Errors block publishing (one of `error`, `warning`)
    - `col` (integer): Column in the YAML (1-based)
    - `line` (integer): Line in the YAML (1-based)
    - `nodeId` (string): The node the finding is about
    - `params` (object): `mail_option_not_allowed`: `option` (`mandatory` or `mailChannel`)
    - `path` (string): Dotted path in the definition
  - `permissions` (array of array of string, required): The any-of permission groups of the actions and events the flow uses
  - `valid` (boolean, required): False when a finding has severity `error`
  - `ports` (object): The output ports of every node that parsed, by node id (the builder's handles)

Example 201 answer:

```json
{
  "flow": {
    "archived": false,
    "canEdit": true,
    "createdAt": "2026-11-18T09:02:11Z",
    "createdBy": "sophie.huber@muster-it.example",
    "enabled": false,
    "id": "5e7a9c1b-3d5f-4a7b-8c9d-1e3f5a7b9c0d",
    "key": "kritische-tickets-melden",
    "name": "Kritische Tickets melden",
    "owner": "personal",
    "ownerEmail": "sophie.huber@muster-it.example",
    "updatedAt": "2026-11-18T09:02:11Z",
    "updatedBy": "sophie.huber@muster-it.example",
    "version": 1
  },
  "validation": {
    "diagnostics": [],
    "permissions": [
      [
        "desk:read",
        "desk:write",
        "desk:admin"
      ]
    ],
    "valid": true
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/flows' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Kritische Tickets melden","owner":"personal","params":{"priorities":["hoch","kritisch"],"recipients":["creator"]},"template":"kritische-tickets-melden"}'
```

## Draft a new personal flow from a description through the ai module (tenant:flows:write|admin)

`POST /api/flows/v1/flows/generate`

Module: Flows · operationId: `generateFlow` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

Picks the catalogue's actions and events the caller holds a permission of, writes the YAML and corrects it with
the validator's findings (at most three attempts). The flow is created as the caller's personal flow with the
draft – also when it is still invalid (`validation` lists the findings) – and never published. 6 per minute
and caller. `503 ai_unavailable` without the ai module, `503 ai_failed` when the model did not answer.

### Request body

`application/json` (required)

- `description` (string, required): What the flow should do (max length 4000)
- `name` (string): The flow's name; default: the description's first words (max length 200)

Example:

```json
{
  "description": "Wenn ein dringendes Ticket angelegt wird, schicke mir eine Mail mit dem Titel.",
  "name": "Dringende Tickets per Mail"
}
```

### Responses

- **201** The new flow with its generated draft (`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`)
- **429** Too many generations
- **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:

- `attempts` (integer, required): How often the draft was written (corrections included)
- `flow` (Flow, required)
  - `archived` (boolean): Whether the flow is archived
  - `canEdit` (boolean): Whether the caller may change the draft and publish (a scoped flow: the owning module lets the caller manage the scope and the token holds tenant:flows:write or admin)
  - `createdAt` (string (date-time)): When the flow was created
  - `createdBy` (string): E-mail of the creator
  - `description` (string): Description from the definition
  - `enabled` (boolean): Whether the published version's triggers start runs
  - `id` (string (uuid)): Flow id
  - `key` (string): Unique per tenant; sub-flows call a flow by it
  - `name` (string): Display name
  - `owner` (string): `personal` (acts as its creator) or `tenant` (acts as its service account) (one of `personal`, `tenant`)
  - `ownerEmail` (string): Personal flows: the owner; tenant flows: who created it
  - `pausedReason` (string): Why runs stopped by themselves (owner_inactive, permission_lost, tripped)
  - `publishedNumber` (integer): The live version
  - `scope` (string): What the flow belongs to – `desk:space:<id>` or `forge:project:<id>`; absent for a tenant or personal flow. The owning module decides who sees and manages a scoped flow ("Scoped flows").
  - `serviceAccountId` (string (uuid)): Tenant flows: the account it acts as
  - `updatedAt` (string (date-time)): When the flow was changed last
  - `updatedBy` (string): E-mail of who changed the flow last
  - `version` (integer): Send it with changes
- `validation` (Validation, required)
  - `diagnostics` (array of Diagnostic, required): Findings of the validator
    - `code` (string, required): Stable code, e.g. `unknown_port`, `invalid_assignee`, `mail_option_not_allowed` (a mail node sets `mandatory` or `mailChannel` in a personal or scoped flow)
    - `message` (string, required): Human-readable explanation
    - `severity` (string, required): Errors block publishing (one of `error`, `warning`)
    - `col` (integer): Column in the YAML (1-based)
    - `line` (integer): Line in the YAML (1-based)
    - `nodeId` (string): The node the finding is about
    - `params` (object): `mail_option_not_allowed`: `option` (`mandatory` or `mailChannel`)
    - `path` (string): Dotted path in the definition
  - `permissions` (array of array of string, required): The any-of permission groups of the actions and events the flow uses
  - `valid` (boolean, required): False when a finding has severity `error`
  - `ports` (object): The output ports of every node that parsed, by node id (the builder's handles)

Example 201 answer:

```json
{
  "attempts": 2,
  "flow": {
    "archived": false,
    "canEdit": true,
    "createdAt": "2026-11-18T09:05:40Z",
    "createdBy": "sophie.huber@muster-it.example",
    "enabled": false,
    "id": "7c9e1b3d-5f7a-4b9c-8d0e-2f4a6c8e0b2d",
    "key": "dringende-tickets-per-mail",
    "name": "Dringende Tickets per Mail",
    "owner": "personal",
    "ownerEmail": "sophie.huber@muster-it.example",
    "updatedAt": "2026-11-18T09:05:40Z",
    "updatedBy": "sophie.huber@muster-it.example",
    "version": 1
  },
  "validation": {
    "diagnostics": [],
    "permissions": [
      [
        "desk:read",
        "desk:write",
        "desk:admin"
      ]
    ],
    "valid": true
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/flows/generate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Wenn ein dringendes Ticket angelegt wird, schicke mir eine Mail mit dem Titel.","name":"Dringende Tickets per Mail"}'
```

## Get a flow (tenant:flows:read|write|admin; scoped flows the owning module's view)

`GET /api/flows/v1/flows/{id}`

Module: Flows · operationId: `getFlow` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

A scoped flow is answered to whoever its module lets view the scope (`404` otherwise, `503 scope_unavailable` when the module cannot answer – see "Scoped flows").

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The flow (`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`)
- **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 200 answer:

- `archived` (boolean): Whether the flow is archived
- `canEdit` (boolean): Whether the caller may change the draft and publish (a scoped flow: the owning module lets the caller manage the scope and the token holds tenant:flows:write or admin)
- `createdAt` (string (date-time)): When the flow was created
- `createdBy` (string): E-mail of the creator
- `description` (string): Description from the definition
- `enabled` (boolean): Whether the published version's triggers start runs
- `id` (string (uuid)): Flow id
- `key` (string): Unique per tenant; sub-flows call a flow by it
- `name` (string): Display name
- `owner` (string): `personal` (acts as its creator) or `tenant` (acts as its service account) (one of `personal`, `tenant`)
- `ownerEmail` (string): Personal flows: the owner; tenant flows: who created it
- `pausedReason` (string): Why runs stopped by themselves (owner_inactive, permission_lost, tripped)
- `publishedNumber` (integer): The live version
- `scope` (string): What the flow belongs to – `desk:space:<id>` or `forge:project:<id>`; absent for a tenant or personal flow. The owning module decides who sees and manages a scoped flow ("Scoped flows").
- `serviceAccountId` (string (uuid)): Tenant flows: the account it acts as
- `updatedAt` (string (date-time)): When the flow was changed last
- `updatedBy` (string): E-mail of who changed the flow last
- `version` (integer): Send it with changes

Example 200 answer:

```json
{
  "archived": false,
  "canEdit": true,
  "createdAt": "2026-10-21T09:20:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "description": "Bei jedem neuen Ticket mit hoher oder kritischer Priorität fasst die KI die Meldung zusammen und die Systemadministration bekommt eine Nachricht.",
  "enabled": true,
  "id": "6f2a9c4e-1b3d-4e5f-8a7b-9c0d1e2f3a4b",
  "key": "kritische-tickets-zusammenfassen",
  "name": "Kritische Tickets zusammenfassen",
  "owner": "personal",
  "ownerEmail": "sophie.huber@muster-it.example",
  "publishedNumber": 2,
  "updatedAt": "2026-11-12T14:03:27Z",
  "updatedBy": "sophie.huber@muster-it.example",
  "version": 5
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Archive a flow (tenant:flows:write|admin; scoped flows the owning module's manage)

`DELETE /api/flows/v1/flows/{id}`

Module: Flows · operationId: `archiveFlow` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `version` | query | integer | yes |  |
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Archived
- **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`)
- **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`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12?version=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Enable or disable a flow, change its service account (tenant:flows:write|admin; scoped flows the owning module's manage)

`PATCH /api/flows/v1/flows/{id}`

Module: Flows · operationId: `updateFlow` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

Enabling needs a published version. A new service account disables the flow until the next publish confirms it.
A scoped flow is changed by whoever its module lets manage the scope, not by `tenant:flows:admin`
(`503 scope_unavailable` when the module cannot answer).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `version` (integer, required): The flow's version you read
- `enabled` (boolean): Enable or disable the flow
- `serviceAccountId` (string (uuid)): Tenant flows: the new service account

Example:

```json
{
  "enabled": false,
  "version": 5
}
```

### Responses

- **200** The flow (`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 200 answer:

- `archived` (boolean): Whether the flow is archived
- `canEdit` (boolean): Whether the caller may change the draft and publish (a scoped flow: the owning module lets the caller manage the scope and the token holds tenant:flows:write or admin)
- `createdAt` (string (date-time)): When the flow was created
- `createdBy` (string): E-mail of the creator
- `description` (string): Description from the definition
- `enabled` (boolean): Whether the published version's triggers start runs
- `id` (string (uuid)): Flow id
- `key` (string): Unique per tenant; sub-flows call a flow by it
- `name` (string): Display name
- `owner` (string): `personal` (acts as its creator) or `tenant` (acts as its service account) (one of `personal`, `tenant`)
- `ownerEmail` (string): Personal flows: the owner; tenant flows: who created it
- `pausedReason` (string): Why runs stopped by themselves (owner_inactive, permission_lost, tripped)
- `publishedNumber` (integer): The live version
- `scope` (string): What the flow belongs to – `desk:space:<id>` or `forge:project:<id>`; absent for a tenant or personal flow. The owning module decides who sees and manages a scoped flow ("Scoped flows").
- `serviceAccountId` (string (uuid)): Tenant flows: the account it acts as
- `updatedAt` (string (date-time)): When the flow was changed last
- `updatedBy` (string): E-mail of who changed the flow last
- `version` (integer): Send it with changes

Example 200 answer:

```json
{
  "archived": false,
  "canEdit": true,
  "createdAt": "2026-10-21T09:20:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "description": "Bei jedem neuen Ticket mit hoher oder kritischer Priorität fasst die KI die Meldung zusammen und die Systemadministration bekommt eine Nachricht.",
  "enabled": true,
  "id": "6f2a9c4e-1b3d-4e5f-8a7b-9c0d1e2f3a4b",
  "key": "kritische-tickets-zusammenfassen",
  "name": "Kritische Tickets zusammenfassen",
  "owner": "personal",
  "ownerEmail": "sophie.huber@muster-it.example",
  "publishedNumber": 2,
  "updatedAt": "2026-11-12T14:03:27Z",
  "updatedBy": "sophie.huber@muster-it.example",
  "version": 5
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"enabled":false,"version":5}'
```

## Get the draft of a flow (tenant:flows:read|write|admin; scoped flows the owning module's view)

`GET /api/flows/v1/flows/{id}/draft`

Module: Flows · operationId: `getFlowDraft` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The draft (`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`)
- **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 200 answer:

- `diagnostics` (array of Diagnostic): Findings of the validator for the draft
  - `code` (string, required): Stable code, e.g. `unknown_port`, `invalid_assignee`, `mail_option_not_allowed` (a mail node sets `mandatory` or `mailChannel` in a personal or scoped flow)
  - `message` (string, required): Human-readable explanation
  - `severity` (string, required): Errors block publishing (one of `error`, `warning`)
  - `col` (integer): Column in the YAML (1-based)
  - `line` (integer): Line in the YAML (1-based)
  - `nodeId` (string): The node the finding is about
  - `params` (object): `mail_option_not_allowed`: `option` (`mandatory` or `mailChannel`)
  - `path` (string): Dotted path in the definition
- `updatedAt` (string (date-time)): When the draft was saved last
- `updatedBy` (string): E-mail of who saved the draft last
- `version` (integer): Optimistic-lock version of the draft; send it with the next save
- `yaml` (string): The draft definition (YAML)

Example 200 answer:

```json
{
  "diagnostics": [],
  "updatedAt": "2026-11-17T10:45:12Z",
  "updatedBy": "sophie.huber@muster-it.example",
  "version": 6,
  "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 GET 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/draft' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Save the draft of a flow, also an invalid one (tenant:flows:write|admin; scoped flows the owning module's manage)

`PUT /api/flows/v1/flows/{id}/draft`

Module: Flows · operationId: `saveFlowDraft` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `version` (integer, required): The draft's version you edited
- `yaml` (string, required): The draft definition (YAML)

Example:

```json
{
  "version": 5,
  "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 }}\" }\nedges:\n  - neues_ticket -\u003e ticket\n"
}
```

### Responses

- **200** The saved draft with its findings (`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`)
- **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 200 answer:

- `diagnostics` (array of Diagnostic): Findings of the validator for the draft
  - `code` (string, required): Stable code, e.g. `unknown_port`, `invalid_assignee`, `mail_option_not_allowed` (a mail node sets `mandatory` or `mailChannel` in a personal or scoped flow)
  - `message` (string, required): Human-readable explanation
  - `severity` (string, required): Errors block publishing (one of `error`, `warning`)
  - `col` (integer): Column in the YAML (1-based)
  - `line` (integer): Line in the YAML (1-based)
  - `nodeId` (string): The node the finding is about
  - `params` (object): `mail_option_not_allowed`: `option` (`mandatory` or `mailChannel`)
  - `path` (string): Dotted path in the definition
- `updatedAt` (string (date-time)): When the draft was saved last
- `updatedBy` (string): E-mail of who saved the draft last
- `version` (integer): Optimistic-lock version of the draft; send it with the next save
- `yaml` (string): The draft definition (YAML)

Example 200 answer:

```json
{
  "diagnostics": [],
  "updatedAt": "2026-11-17T10:45:12Z",
  "updatedBy": "sophie.huber@muster-it.example",
  "version": 6,
  "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 PUT 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/draft' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"version":5,"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 }}\" }\nedges:\n  - neues_ticket -\u003e ticket\n"}'
```

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

## List the published versions of a flow (tenant:flows:read|write|admin; scoped flows the owning module's view)

`GET /api/flows/v1/flows/{id}/versions`

Module: Flows · operationId: `listFlowVersions` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Versions, newest first (`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`)
- **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 200 answer:

- `items` (array of Version, required): Versions
  - `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
- `total` (integer): Number of items

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-11-12T14:03:27Z",
      "createdBy": "sophie.huber@muster-it.example",
      "note": "Empfänger auf die Systemadministration umgestellt",
      "number": 2,
      "permissions": [
        "desk:read"
      ]
    },
    {
      "createdAt": "2026-10-21T09:41:00Z",
      "createdBy": "sophie.huber@muster-it.example",
      "note": "Erste Fassung",
      "number": 1,
      "permissions": [
        "desk:read"
      ]
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/versions' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get a published version with its definition (tenant:flows:read|write|admin; scoped flows the owning module's view)

`GET /api/flows/v1/flows/{id}/versions/{number}`

Module: Flows · operationId: `getFlowVersion` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `number` | path | integer | yes |  |

### Responses

- **200** The 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`)
- **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 200 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 200 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 GET 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/versions/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Copy a published version into the draft (tenant:flows:write|admin; scoped flows the owning module's manage)

`POST /api/flows/v1/flows/{id}/versions/{number}/restore`

Module: Flows · operationId: `restoreFlowVersion` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `number` | path | integer | yes |  |

### Request body

`application/json` (required)

- `version` (integer, required): The draft's current version

Example:

```json
{
  "version": 6
}
```

### Responses

- **200** The draft (`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`)
- **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 200 answer:

- `diagnostics` (array of Diagnostic): Findings of the validator for the draft
  - `code` (string, required): Stable code, e.g. `unknown_port`, `invalid_assignee`, `mail_option_not_allowed` (a mail node sets `mandatory` or `mailChannel` in a personal or scoped flow)
  - `message` (string, required): Human-readable explanation
  - `severity` (string, required): Errors block publishing (one of `error`, `warning`)
  - `col` (integer): Column in the YAML (1-based)
  - `line` (integer): Line in the YAML (1-based)
  - `nodeId` (string): The node the finding is about
  - `params` (object): `mail_option_not_allowed`: `option` (`mandatory` or `mailChannel`)
  - `path` (string): Dotted path in the definition
- `updatedAt` (string (date-time)): When the draft was saved last
- `updatedBy` (string): E-mail of who saved the draft last
- `version` (integer): Optimistic-lock version of the draft; send it with the next save
- `yaml` (string): The draft definition (YAML)

Example 200 answer:

```json
{
  "diagnostics": [],
  "updatedAt": "2026-11-17T10:45:12Z",
  "updatedBy": "sophie.huber@muster-it.example",
  "version": 6,
  "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/versions/1/restore' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"version":6}'
```

## List the triggers of the published version with their state (tenant:flows:read|write|admin; scoped flows the owning module's view)

`GET /api/flows/v1/flows/{id}/triggers`

Module: Flows · operationId: `listFlowTriggers` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

A schedule shows its next and last fire. A webhook's token and secret are never shown here.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Triggers, by id (`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`)
- **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 200 answer:

- `items` (array of Trigger, required): Triggers
  - `activatedAt` (string (date-time), required): Events before this time do not start the flow
  - `id` (string, required): Trigger id in the definition
  - `kind` (string, required): Trigger kind (one of `event`, `schedule`, `manual`, `webhook`)
  - `auth` (string): Authentication of a webhook (one of `token`, `hmac`)
  - `cron` (string): Cron expression of a schedule
  - `event` (string): Event type of an event trigger
  - `lastFiredAt` (string (date-time)): Last start by this trigger
  - `nextFireAt` (string (date-time)): Next slot of a schedule
  - `timezone` (string): Time zone of a schedule
- `total` (integer): Number of items

Example 200 answer:

```json
{
  "items": [
    {
      "activatedAt": "2026-10-25T14:05:00Z",
      "cron": "0 8 * * 1",
      "id": "montags",
      "kind": "schedule",
      "lastFiredAt": "2026-11-16T07:00:01Z",
      "nextFireAt": "2026-11-23T07:00:00Z",
      "timezone": "Europe/Berlin"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/triggers' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Give a webhook trigger a new token and signing secret (tenant:flows:write|admin; scoped flows the owning module's manage)

`POST /api/flows/v1/flows/{id}/triggers/{trigger}/rotate`

Module: Flows · operationId: `rotateFlowWebhook` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

The old token and secret stop at once. The answer is the only place the new ones are shown.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `trigger` | path | string | yes |  |

### Responses

- **200** The new credentials (`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 200 answer:

- `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)>

Example 200 answer:

```json
{
  "path": "/api/flows/v1/hooks/fw_EXAMPLE7Vb2mX9kT4rL8nW3pZ6cY1f",
  "secret": "whsec_EXAMPLEq4Lm8Rt2Vx6Zb0Nc3Fh7Jk1",
  "token": "fw_EXAMPLE7Vb2mX9kT4rL8nW3pZ6cY1f",
  "trigger": "shop_bestellung"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/triggers/string/rotate' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The tenant's limits of flows and the platform's (tenant:flows:read|write|admin)

`GET /api/flows/v1/settings`

Module: Flows · operationId: `getFlowsSettings` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

A tenant may lower four limits below the platform's: the breaker (`maxRunsPerMinute` – a flow started more
often by events or webhooks pauses), a run's deadline when its flow sets none (`runTimeoutHours`), the node
activations of one run (`maxSteps`) and how long finished runs are kept (`retentionDays`). `null` is the
platform's value (`platform`). Changes apply to new runs and checks within 30 seconds.

### Responses

- **200** The settings (`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`)

Fields of the 200 answer:

- `maxRunsPerMinute` (integer, nullable): The breaker – starts by events or webhooks per flow and minute
- `maxSteps` (integer, nullable): Node activations of one run
- `retentionDays` (integer, nullable): Finished runs are deleted after this many days
- `runTimeoutHours` (integer, nullable): A run's deadline when its flow sets none
- `platform` (FlowsLimits, required)
  - `maxRunsPerMinute` (integer, nullable): The breaker – starts by events or webhooks per flow and minute
  - `maxSteps` (integer, nullable): Node activations of one run
  - `retentionDays` (integer, nullable): Finished runs are deleted after this many days
  - `runTimeoutHours` (integer, nullable): A run's deadline when its flow sets none
- `version` (integer, required): 0 until the first save
- `updatedAt` (string (date-time)): When the settings were saved last; absent before the first save
- `updatedBy` (string): E-mail of who saved the settings last; absent before the first save

Example 200 answer:

```json
{
  "maxRunsPerMinute": 30,
  "maxSteps": 500,
  "platform": {
    "maxRunsPerMinute": 60,
    "maxSteps": 1000,
    "retentionDays": 90,
    "runTimeoutHours": 720
  },
  "retentionDays": 30,
  "runTimeoutHours": null,
  "updatedAt": "2026-10-02T11:30:00Z",
  "updatedBy": "thomas.pfeiffer@muster-it.example",
  "version": 3
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Replace the tenant's limits of flows (tenant:flows:admin)

`PUT /api/flows/v1/settings`

Module: Flows · operationId: `updateFlowsSettings` · Tag: Flows · Auth: access token (`Authorization: Bearer <accessToken>`)

Every limit is `null` (the platform's) or between 1 and the platform's value. Send the `version` read (0 before the first save); a stale one answers `409 version_conflict`.

### Request body

`application/json` (required)

- `maxRunsPerMinute` (integer, nullable): The breaker – starts by events or webhooks per flow and minute
- `maxSteps` (integer, nullable): Node activations of one run
- `retentionDays` (integer, nullable): Finished runs are deleted after this many days
- `runTimeoutHours` (integer, nullable): A run's deadline when its flow sets none
- `version` (integer, required): The settings version read (0 before the first save)

Example:

```json
{
  "maxRunsPerMinute": 30,
  "maxSteps": 500,
  "retentionDays": 30,
  "runTimeoutHours": null,
  "version": 3
}
```

### Responses

- **200** The saved settings (`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`)
- **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`)

Fields of the 200 answer:

- `maxRunsPerMinute` (integer, nullable): The breaker – starts by events or webhooks per flow and minute
- `maxSteps` (integer, nullable): Node activations of one run
- `retentionDays` (integer, nullable): Finished runs are deleted after this many days
- `runTimeoutHours` (integer, nullable): A run's deadline when its flow sets none
- `platform` (FlowsLimits, required)
  - `maxRunsPerMinute` (integer, nullable): The breaker – starts by events or webhooks per flow and minute
  - `maxSteps` (integer, nullable): Node activations of one run
  - `retentionDays` (integer, nullable): Finished runs are deleted after this many days
  - `runTimeoutHours` (integer, nullable): A run's deadline when its flow sets none
- `version` (integer, required): 0 until the first save
- `updatedAt` (string (date-time)): When the settings were saved last; absent before the first save
- `updatedBy` (string): E-mail of who saved the settings last; absent before the first save

Example 200 answer:

```json
{
  "maxRunsPerMinute": 30,
  "maxSteps": 500,
  "platform": {
    "maxRunsPerMinute": 60,
    "maxSteps": 1000,
    "retentionDays": 90,
    "runTimeoutHours": 720
  },
  "retentionDays": 30,
  "runTimeoutHours": null,
  "updatedAt": "2026-10-02T11:30:00Z",
  "updatedBy": "thomas.pfeiffer@muster-it.example",
  "version": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/flows/v1/settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"maxRunsPerMinute":30,"maxSteps":500,"retentionDays":30,"runTimeoutHours":null,"version":3}'
```

# Runs

## Run the draft as a test – dry by default, live with tenant:flows:admin (tenant:flows:write for own flows; scoped flows the owning module's manage)

`POST /api/flows/v1/flows/{id}/test-runs`

Module: Flows · operationId: `testFlowDraft` · Tag: Runs · Auth: access token (`Authorization: Bearer <accessToken>`)

Who may change the flow may test it (a scoped flow: who its module lets manage the scope; a live test still
needs `tenant:flows:admin`). The draft must be valid (`422 invalid_definition`); HR confirms its permissions like a publish
(`422 permission_missing`; a token with a subset of the permissions must hold them itself, `403 forbidden_grant`). The run is pinned to a snapshot of the draft and marked with `testMode`. A **dry**
test (default) simulates every write node (its output is a sample of the operation's answer, its input says
`dryRun`), resolves but sends no mail and asks only the tester in human tasks; reads and AI nodes run for real.
A **live** test (`live: true`, `403 live_test_forbidden` without tenant:flows:admin) acts like a run. The flow
need not be published or enabled; dry tests are not billed. Sub-flows run in the same mode.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `input` (object): trigger.data: an input, or a sample event or webhook body
- `live` (boolean): Send the writes for real (needs tenant:flows:admin) (default `false`)
- `trigger` (string): The trigger the test acts as (any kind); default the first manual one

Example:

```json
{
  "input": {
    "itemId": "4e6a8c0b-2d4f-4a1b-9c3e-5f7a9b1c3d5e",
    "number": "SUP-214",
    "priority": "hoch",
    "title": "WLAN im Restaurant fällt aus"
  },
  "live": false,
  "trigger": "neues_ticket"
}
```

### Responses

- **202** Started (`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 202 answer:

- `runId` (string (uuid), required): The test run

Example 202 answer:

```json
{
  "runId": "2d4f6a8c-0e1b-4d3f-9a5c-7e9b1d3f5a7c"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/test-runs' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"input":{"itemId":"4e6a8c0b-2d4f-4a1b-9c3e-5f7a9b1c3d5e","number":"SUP-214","priority":"hoch","title":"WLAN im Restaurant fällt aus"},"live":false,"trigger":"neues_ticket"}'
```

## Start a flow from an inbound webhook (public; the token is the credential)

`POST /api/flows/v1/hooks/{token}`

Module: Flows · operationId: `receiveFlowWebhook` · Tag: Runs · Auth: none

The JSON body (at most 1 MiB) becomes `trigger.data`. A webhook with `auth: hmac` also needs the header
`X-Flows-Signature: sha256=<hex of HMAC-SHA256(secret, raw body)>` (`401 invalid_signature`); the key is the
secret exactly as shown at publish or rotation (its characters, not hex-decoded). Needs no access token: the
token in the path is the credential – keep it secret like an API key. `Content-Type` must be
`application/json` (`415 unsupported_media_type`). An unknown token, or a flow that is archived or not
published, answers 404; a disabled one `409 flow_disabled`. With an
`Idempotency-Key` header a repeated call answers the same run (`created: false`). A trigger `filter` that is false
starts nothing (`runId` null). A flow started more than 60 times in a minute pauses (`409 flow_tripped`).
Rate-limited per client IP.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string |  | (max length 200) |
| `X-Flows-Signature` | header | string |  |  |
| `token` | path | string | yes | (max length 128) |

### Request body

`application/json` (required)

Example:

```json
{
  "currency": "EUR",
  "customer": "Alpenhotel Seeblick GmbH",
  "event": "order.created",
  "orderNo": "SO-10482",
  "total": 1249.9
}
```

### Responses

- **202** Accepted (`application/json`)
- **400** Invalid input (`invalid`); `field` names the first invalid field, `details.fields` every one. (`application/json`)
- **401** invalid_signature (`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`)
- **413** too_large (`application/json`)
- **415** unsupported_media_type (`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`)
- **429** Too many calls from this address

Fields of the 202 answer:

- `created` (boolean, required): False when an Idempotency-Key repeated an earlier call
- `runId` (string (uuid), nullable, required): The started run; null when the trigger's filter did not hold

Example 202 answer:

```json
{
  "created": true,
  "runId": "4a6c8e0b-2d4f-4b6a-8c9e-1f3a5c7e9b0d"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/hooks/string' \
  -H 'Content-Type: application/json' \
  --data '{"currency":"EUR","customer":"Alpenhotel Seeblick GmbH","event":"order.created","orderNo":"SO-10482","total":1249.9}'
```

## Start a run of a flow by hand (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}/runs`

Module: Flows · operationId: `startFlowRun` · Tag: Runs · Auth: access token (`Authorization: Bearer <accessToken>`)

Runs the published version from a manual trigger (`trigger`, default the first one) with `input` as
`trigger.data`. The run acts with the flow owner's permissions (or the service account's), so who may change
the flow may start it – a scoped flow: who its module lets manage the scope (`503 scope_unavailable` when the
module cannot answer). An `Idempotency-Key` makes a repeated start the same run (`created: false`). A manual
trigger may carry a `filter` over `trigger.data`: a start it does not hold for is 422 `not_applicable`, one
whose filter cannot be evaluated for the input 422 `filter_failed`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string |  | (max length 200) |
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `input` (object): Start data of the run (`trigger.data`)
- `trigger` (string): The id of a manual trigger

Example:

```json
{
  "input": {
    "amount": 120
  },
  "trigger": "von_hand"
}
```

### Responses

- **202** Started (or, with a known Idempotency-Key, the existing run) (`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 202 answer:

- `created` (boolean, required): False when an Idempotency-Key returned an existing run
- `runId` (string (uuid), required): The run

Example 202 answer:

```json
{
  "created": true,
  "runId": "6c8e0a2b-4d6f-4a8c-9e1b-3d5f7a9c1e3b"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/flows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/runs' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"input":{"amount":120},"trigger":"von_hand"}'
```

## Change notices for open flows pages (tenant:flows:read|write|admin|tasks)

`GET /api/flows/v1/live`

Module: Flows · operationId: `streamFlowsLiveChanges` · Tag: Runs · Auth: access token (`Authorization: Bearer <accessToken>`)

Answers `text/event-stream` (`X-Accel-Buffering: no`, a `: ping` comment every 15 seconds). First a `ready` event
(`{}`), then one `change` event per flow, run or task change the caller may see – with the rules of the read
routes: a flow as `GET /flows/{id}`, a run as `GET /runs/{id}`, a task as `GET /tasks/{id}` (its assignees with
`tenant:flows:tasks`, and who sees its run) – about one to two seconds after the commit; a new stream starts with
the changes of the last 10 seconds. A notice only names what changed (ids, action, state) – never names, data or
definitions; the client reloads through the API. `kind` is `flow` (`action` created, updated, published,
archived, tripped), `run` (`action` started, succeeded, failed, cancelled; `status` of an ended run), `task`
(`action` created, completed; `status`) or `resync` (notices were dropped: reload everything shown). When the
token expires, and after 15 minutes at the latest, the stream ends with a `reconnect` event (`{}`): reconnecting
within 10 seconds loses nothing. At most 10 open streams per person and 500 per tenant and server instance
(429 `rate_limited`).

The notices of a scoped flow (its flow, run and task changes) reach only a stream that names its scope with
`scope` – besides a task's assignees, who always hear of their task. Each named scope is checked once, when
the stream opens: the module that owns it must let the caller view it (`404` otherwise, `503
scope_unavailable` when it cannot answer); the check is repeated at every reconnect, so a changed answer
applies after 15 minutes at the latest. A stream that names scopes still carries the caller's other notices.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | array of string |  | Also stream the changes of this scope's flows (`desk:space:<id>`, `forge:project:<id>`); repeatable, at most 10 (`400 invalid`, field `scope`) |

### Responses

- **200** Event stream (`text/event-stream`)
- **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`)
- **429** Too many open streams (`rate_limited`)
- **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 200 answer:

- `kind` (string, required): What changed (one of `flow`, `run`, `task`, `resync`)
- `action` (string): What happened to it
- `flowId` (string (uuid)): The flow
- `runId` (string (uuid)): The run
- `status` (string): State of an ended run or of a task
- `taskId` (string (uuid)): The task

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/live' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the runs the caller may see (tenant:flows:read|write|admin; a scoped flow's runs with the owning module's view)

`GET /api/flows/v1/runs`

Module: Flows · operationId: `listFlowRuns` · Tag: Runs · Auth: access token (`Authorization: Bearer <accessToken>`)

Runs of tenant flows for every flows permission; runs of personal flows only for their owner. Newest first.
The runs of a scoped flow are listed only with its `flowId`, for whoever its module lets view the scope (an
empty list otherwise, `503 scope_unavailable` when the module cannot answer); without `flowId` the list holds
runs of flows without scope only.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `flowId` | query | string (uuid) |  |  |
| `status` | query | string |  | (one of `running`, `succeeded`, `failed`, `cancelled`) |
| `limit` | query | integer |  | (default `50`; max 200) |
| `cursor` | query | string |  | nextCursor of the previous page |

### Responses

- **200** Runs (`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`)
- **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 200 answer:

- `items` (array of RunSummary, required): Runs
  - `createdAt` (string (date-time)): When the run started
  - `error` (NodeError)
    - `attempt` (integer): Attempt the error happened in
    - `code` (string): Stable error code
    - `details` (object): Further facts of the error
    - `message` (string): Human-readable message
    - `node` (string): Id of the node that failed
  - `finishedAt` (string (date-time)): When the run ended; absent while running
  - `flowId` (string (uuid)): Id of the flow
  - `flowKey` (string): Key of the flow
  - `flowName` (string): Name of the flow
  - `id` (string (uuid)): Run id
  - `startedBy` (string): Who or what started the run
  - `status` (string): State of the run (one of `running`, `succeeded`, `failed`, `cancelled`)
  - `steps` (integer): Node activations so far
  - `testMode` (string): A test run of a draft (dry: writes simulated); absent for a normal run (one of `dry`, `live`)
  - `trigger` (string): The trigger's id
  - `triggerKind` (string): Kind of the trigger that started the run (one of `event`, `schedule`, `manual`, `webhook`)
- `nextCursor` (string): Cursor of the next page; absent on the last page

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-11-18T07:59:02Z",
      "finishedAt": "2026-11-18T07:59:04Z",
      "flowId": "6f2a9c4e-1b3d-4e5f-8a7b-9c0d1e2f3a4b",
      "flowKey": "kritische-tickets-zusammenfassen",
      "flowName": "Kritische Tickets zusammenfassen",
      "id": "9a1b3c5d-7e2f-4a6b-8c0d-1e3f5a7b9c2d",
      "startedBy": "event desk.item.created",
      "status": "succeeded",
      "steps": 2,
      "trigger": "neues_ticket",
      "triggerKind": "event"
    },
    {
      "createdAt": "2026-11-16T07:00:01Z",
      "error": {
        "attempt": 3,
        "code": "module_error",
        "message": "crm antwortete mit 503 (Dienst nicht erreichbar).",
        "node": "offene"
      },
      "finishedAt": "2026-11-16T07:04:12Z",
      "flowId": "0e2a4c6e-8b1d-4f3a-9c5e-7b9d1f3a5c7e",
      "flowKey": "offene-chancen-montag",
      "flowName": "Offene Chancen zum Wochenstart",
      "id": "1b3d5f7a-9c1e-4a3b-8d5f-7a9c1e3b5d7f",
      "startedBy": "schedule",
      "status": "failed",
      "steps": 1,
      "trigger": "montags",
      "triggerKind": "schedule"
    }
  ],
  "nextCursor": "eyJjIjoiMjAyNi0xMS0xNlQwNzowMDowMVoiLCJpZCI6IjFiM2Q1ZjdhIn0"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/runs' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get a run with its node history (tenant:flows:read|write|admin; a scoped flow's run with the owning module's view)

`GET /api/flows/v1/runs/{id}`

Module: Flows · operationId: `getFlowRun` · Tag: Runs · Auth: access token (`Authorization: Bearer <accessToken>`)

The run, the YAML of the version it ran, and per node its input, output, attempts and error. The run of a
scoped flow is answered to whoever its module lets view the scope (`404` otherwise, `503 scope_unavailable`
when the module cannot answer).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The run (`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`)
- **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 200 answer:

- `createdAt` (string (date-time)): When the run started
- `error` (NodeError)
  - `attempt` (integer): Attempt the error happened in
  - `code` (string): Stable error code
  - `details` (object): Further facts of the error
  - `message` (string): Human-readable message
  - `node` (string): Id of the node that failed
- `finishedAt` (string (date-time)): When the run ended; absent while running
- `flowId` (string (uuid)): Id of the flow
- `flowKey` (string): Key of the flow
- `flowName` (string): Name of the flow
- `id` (string (uuid)): Run id
- `startedBy` (string): Who or what started the run
- `status` (string): State of the run (one of `running`, `succeeded`, `failed`, `cancelled`)
- `steps` (integer): Node activations so far
- `testMode` (string): A test run of a draft (dry: writes simulated); absent for a normal run (one of `dry`, `live`)
- `trigger` (string): The trigger's id
- `triggerKind` (string): Kind of the trigger that started the run (one of `event`, `schedule`, `manual`, `webhook`)
- `activations` (array of Activation): Every node execution of the run
  - `attempt` (integer): Number of the current or last attempt
  - `attempts` (array of object): Every failed attempt (at
  - `createdAt` (string (date-time)): When the node was reached
  - `dueAt` (string (date-time)): The next attempt of a node waiting for a retry
  - `error` (NodeError)
    - `attempt` (integer): Attempt the error happened in
    - `code` (string): Stable error code
    - `details` (object): Further facts of the error
    - `message` (string): Human-readable message
    - `node` (string): Id of the node that failed
  - `finishedAt` (string (date-time)): When the node ended
  - `handled` (boolean): An error port took the failure over
  - `id` (string (uuid)): Activation id
  - `input` (object): Resolved parameters; error on an error path
  - `kind` (string): The node kind, e.g. `action`, `if`, `human_task`
  - `nodeId` (string): The node's id in the definition
  - `output` (any): The node's output
  - `outputSize` (integer): Size of the output in bytes
  - `port` (string): The port the node left on
  - `scopeKey` (string): The loop iteration: empty at the top, "each[2]", nested "a[0]/b[1]"
  - `startedAt` (string (date-time)): When the node started running
  - `state` (object): A parking node's working state (a foreach's items and results, a sub-flow's child run)
  - `status` (string): skipped: no path reached the node (one of `pending`, `running`, `waiting`, `succeeded`, `failed`, `cancelled`, `skipped`)
- `cancelledBy` (string): E-mail of who cancelled the run
- `definition` (string): The YAML of the version the run ran
- `output` (any): The output of the run's end node
- `timeoutAt` (string (date-time)): When the run times out
- `triggerData` (object): The data the run started with (`trigger.data`)
- `vars` (object): The run's variables
- `version` (integer): Number of the published version the run is pinned to

Example 200 answer:

```json
{
  "activations": [
    {
      "attempt": 1,
      "createdAt": "2026-11-18T07:59:02Z",
      "finishedAt": "2026-11-18T07:59:03Z",
      "id": "1d3f5a7b-9c2e-4a4b-8d6f-0a2c4e6a8b1d",
      "input": {
        "ref": "4e6a8c0b-2d4f-4a1b-9c3e-5f7a9b1c3d5e"
      },
      "kind": "action",
      "nodeId": "ticket",
      "outputSize": 1834,
      "port": "success",
      "startedAt": "2026-11-18T07:59:02Z",
      "status": "succeeded"
    },
    {
      "attempt": 1,
      "createdAt": "2026-11-18T07:59:03Z",
      "finishedAt": "2026-11-18T07:59:04Z",
      "id": "3f5a7b9c-1e4a-4b6d-8f0a-2c4e6a8b0d3f",
      "input": {
        "subject": "Kritisches Ticket SUP-214",
        "to": [
          "person:jonas.bauer@muster-it.example"
        ]
      },
      "kind": "mail",
      "nodeId": "info",
      "output": {
        "sent": 1
      },
      "outputSize": 12,
      "port": "success",
      "startedAt": "2026-11-18T07:59:03Z",
      "status": "succeeded"
    }
  ],
  "createdAt": "2026-11-18T07:59:02Z",
  "finishedAt": "2026-11-18T07:59:04Z",
  "flowId": "6f2a9c4e-1b3d-4e5f-8a7b-9c0d1e2f3a4b",
  "flowKey": "kritische-tickets-zusammenfassen",
  "flowName": "Kritische Tickets zusammenfassen",
  "id": "9a1b3c5d-7e2f-4a6b-8c0d-1e3f5a7b9c2d",
  "startedBy": "event desk.item.created",
  "status": "succeeded",
  "steps": 2,
  "trigger": "neues_ticket",
  "triggerData": {
    "itemId": "4e6a8c0b-2d4f-4a1b-9c3e-5f7a9b1c3d5e",
    "number": "SUP-214",
    "priority": "hoch",
    "title": "WLAN im Restaurant fällt aus"
  },
  "triggerKind": "event",
  "vars": {},
  "version": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/runs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Cancel a running run (tenant:flows:write|admin; a scoped flow's run with the owning module's manage)

`POST /api/flows/v1/runs/{id}/cancel`

Module: Flows · operationId: `cancelFlowRun` · Tag: Runs · Auth: access token (`Authorization: Bearer <accessToken>`)

Waiting nodes are cancelled; a node that is calling a module finishes its call, but nothing follows it. Who
may change the flow may cancel its runs (a scoped flow: who its module lets manage the scope).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Cancelled
- **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`)
- **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`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/runs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/cancel' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Tasks

## List the caller's tasks, open or done (tenant:flows:tasks, a person)

`GET /api/flows/v1/tasks`

Module: Flows · operationId: `listFlowTasks` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | string |  | (one of `open`, `done`; default `"open"`) |
| `limit` | query | integer |  | (default `50`; max 200) |
| `cursor` | query | string |  |  |

### Responses

- **200** Tasks assigned to the caller, newest first (`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`)

Fields of the 200 answer:

- `items` (array of Task, required): Tasks
  - `assignees` (array of string, required): E-mail addresses of the people who may answer
  - `body` (string, required): Text, rendered when the task was created
  - `canAnswer` (boolean, required): The caller is an assignee of the open task
  - `createdAt` (string (date-time), required): When the task was created
  - `flowId` (string (uuid), required): Id of the flow
  - `flowName` (string, required): Name of the flow
  - `form` (array of object, required): The fields to fill in
    - `key` (string, required): Key of the value in `values`
    - `label` (string, required): Label of the field
    - `type` (string, required): Input type (one of `text`, `longtext`, `number`, `bool`, `select`, `date`)
    - `options` (array of string): The choices of a `select` field
    - `required` (boolean): The field must be filled in
  - `id` (string (uuid), required): Task id
  - `nodeId` (string, required): Id of the human_task node
  - `runId` (string (uuid), required): Id of the run that created the task
  - `status` (string, required): State of the task (one of `open`, `completed`, `timed_out`, `cancelled`)
  - `title` (string, required): Title, rendered when the task was created
  - `type` (string, required): `approval` (approve or reject) or `form` (fill in fields) (one of `approval`, `form`)
  - `comment` (string): Comment of the answer
  - `completedAt` (string (date-time)): When the task was answered or closed
  - `completedBy` (string): E-mail of who answered
  - `deadlineAt` (string (date-time)): Deadline of the task
  - `outcome` (string): How the task was answered or ended (one of `approved`, `rejected`, `completed`, `timeout`)
  - `values` (object): The submitted form values
- `nextCursor` (string): Cursor of the next page; absent on the last page

Example 200 answer:

```json
{
  "items": [
    {
      "assignees": [
        "laura.kaestner@muster-it.example"
      ],
      "body": "Lukas Wimmer bittet um Freigabe der Bestellung für die neuen Arbeitsplätze im Vertrieb.",
      "canAnswer": true,
      "createdAt": "2026-11-18T08:14:31Z",
      "deadlineAt": "2026-11-20T16:00:00Z",
      "flowId": "2c8d4e6f-0a1b-4c3d-9e5f-7a8b9c0d1e2f",
      "flowName": "Beschaffung freigeben",
      "form": [
        {
          "key": "kostenstelle",
          "label": "Kostenstelle",
          "options": [
            "4100 Vertrieb",
            "4200 Technik"
          ],
          "required": true,
          "type": "select"
        }
      ],
      "id": "0b7e3c9a-5d1f-4a2b-8c6e-4f9a1b2c3d5e",
      "nodeId": "freigabe",
      "runId": "9a1b3c5d-7e2f-4a6b-8c0d-1e3f5a7b9c2d",
      "status": "open",
      "title": "Freigabe: 3 × Lenovo ThinkPad T14 Gen 5 (3.147,00 € netto)",
      "type": "approval"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/tasks' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Count the caller's open tasks (tenant:flows:tasks, a person)

`GET /api/flows/v1/tasks/count`

Module: Flows · operationId: `countFlowTasks` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** The count (`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`)

Fields of the 200 answer:

- `open` (integer, required): Number of open tasks assigned to the caller

Example 200 answer:

```json
{
  "open": 3
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/tasks/count' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get a task (its assignees; read-only for whoever sees the run) (tenant:flows:tasks, a person)

`GET /api/flows/v1/tasks/{id}`

Module: Flows · operationId: `getFlowTask` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

Besides its assignees a task is read by the owner of a personal flow, by flows admins for a tenant flow and,
for a scoped flow, by whoever its module lets manage the scope (asked only for a caller who is no assignee:
`503 scope_unavailable` when the module cannot answer).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The task (`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`)
- **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 200 answer:

- `assignees` (array of string, required): E-mail addresses of the people who may answer
- `body` (string, required): Text, rendered when the task was created
- `canAnswer` (boolean, required): The caller is an assignee of the open task
- `createdAt` (string (date-time), required): When the task was created
- `flowId` (string (uuid), required): Id of the flow
- `flowName` (string, required): Name of the flow
- `form` (array of object, required): The fields to fill in
  - `key` (string, required): Key of the value in `values`
  - `label` (string, required): Label of the field
  - `type` (string, required): Input type (one of `text`, `longtext`, `number`, `bool`, `select`, `date`)
  - `options` (array of string): The choices of a `select` field
  - `required` (boolean): The field must be filled in
- `id` (string (uuid), required): Task id
- `nodeId` (string, required): Id of the human_task node
- `runId` (string (uuid), required): Id of the run that created the task
- `status` (string, required): State of the task (one of `open`, `completed`, `timed_out`, `cancelled`)
- `title` (string, required): Title, rendered when the task was created
- `type` (string, required): `approval` (approve or reject) or `form` (fill in fields) (one of `approval`, `form`)
- `comment` (string): Comment of the answer
- `completedAt` (string (date-time)): When the task was answered or closed
- `completedBy` (string): E-mail of who answered
- `deadlineAt` (string (date-time)): Deadline of the task
- `outcome` (string): How the task was answered or ended (one of `approved`, `rejected`, `completed`, `timeout`)
- `values` (object): The submitted form values

Example 200 answer:

```json
{
  "assignees": [
    "laura.kaestner@muster-it.example"
  ],
  "body": "Lukas Wimmer bittet um Freigabe der Bestellung für die neuen Arbeitsplätze im Vertrieb.",
  "canAnswer": true,
  "createdAt": "2026-11-18T08:14:31Z",
  "deadlineAt": "2026-11-20T16:00:00Z",
  "flowId": "2c8d4e6f-0a1b-4c3d-9e5f-7a8b9c0d1e2f",
  "flowName": "Beschaffung freigeben",
  "form": [
    {
      "key": "kostenstelle",
      "label": "Kostenstelle",
      "options": [
        "4100 Vertrieb",
        "4200 Technik"
      ],
      "required": true,
      "type": "select"
    }
  ],
  "id": "0b7e3c9a-5d1f-4a2b-8c6e-4f9a1b2c3d5e",
  "nodeId": "freigabe",
  "runId": "9a1b3c5d-7e2f-4a6b-8c0d-1e3f5a7b9c2d",
  "status": "open",
  "title": "Freigabe: 3 × Lenovo ThinkPad T14 Gen 5 (3.147,00 € netto)",
  "type": "approval"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/tasks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Answer a task – approve, reject or fill its form (tenant:flows:tasks, an assignee)

`POST /api/flows/v1/tasks/{id}/answer`

Module: Flows · operationId: `answerFlowTask` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

An approval needs `outcome` approved or rejected (required form fields only when approved); a form task needs
its required fields. Values are checked against the form (`400 invalid` with `field` values.<key>). The run
continues on the outcome's port. Someone who is no assignee gets 404, the run's starter of a node with
`excludeStarter` 403 `starter_excluded`, a task answered, timed out or cancelled 409 `task_closed`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `comment` (string): Comment stored with the answer (max length 4000)
- `outcome` (string): `approved` or `rejected` for an approval (one of `approved`, `rejected`, `completed`)
- `values` (object): Form values by field key

Example:

```json
{
  "comment": "Passt, bitte beim Stammlieferanten bestellen.",
  "outcome": "approved",
  "values": {
    "kostenstelle": "4100 Vertrieb"
  }
}
```

### Responses

- **200** The answered task (`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`)

Fields of the 200 answer:

- `assignees` (array of string, required): E-mail addresses of the people who may answer
- `body` (string, required): Text, rendered when the task was created
- `canAnswer` (boolean, required): The caller is an assignee of the open task
- `createdAt` (string (date-time), required): When the task was created
- `flowId` (string (uuid), required): Id of the flow
- `flowName` (string, required): Name of the flow
- `form` (array of object, required): The fields to fill in
  - `key` (string, required): Key of the value in `values`
  - `label` (string, required): Label of the field
  - `type` (string, required): Input type (one of `text`, `longtext`, `number`, `bool`, `select`, `date`)
  - `options` (array of string): The choices of a `select` field
  - `required` (boolean): The field must be filled in
- `id` (string (uuid), required): Task id
- `nodeId` (string, required): Id of the human_task node
- `runId` (string (uuid), required): Id of the run that created the task
- `status` (string, required): State of the task (one of `open`, `completed`, `timed_out`, `cancelled`)
- `title` (string, required): Title, rendered when the task was created
- `type` (string, required): `approval` (approve or reject) or `form` (fill in fields) (one of `approval`, `form`)
- `comment` (string): Comment of the answer
- `completedAt` (string (date-time)): When the task was answered or closed
- `completedBy` (string): E-mail of who answered
- `deadlineAt` (string (date-time)): Deadline of the task
- `outcome` (string): How the task was answered or ended (one of `approved`, `rejected`, `completed`, `timeout`)
- `values` (object): The submitted form values

Example 200 answer:

```json
{
  "assignees": [
    "laura.kaestner@muster-it.example"
  ],
  "body": "Lukas Wimmer bittet um Freigabe der Bestellung für die neuen Arbeitsplätze im Vertrieb.",
  "canAnswer": true,
  "createdAt": "2026-11-18T08:14:31Z",
  "deadlineAt": "2026-11-20T16:00:00Z",
  "flowId": "2c8d4e6f-0a1b-4c3d-9e5f-7a8b9c0d1e2f",
  "flowName": "Beschaffung freigeben",
  "form": [
    {
      "key": "kostenstelle",
      "label": "Kostenstelle",
      "options": [
        "4100 Vertrieb",
        "4200 Technik"
      ],
      "required": true,
      "type": "select"
    }
  ],
  "id": "0b7e3c9a-5d1f-4a2b-8c6e-4f9a1b2c3d5e",
  "nodeId": "freigabe",
  "runId": "9a1b3c5d-7e2f-4a6b-8c0d-1e3f5a7b9c2d",
  "status": "open",
  "title": "Freigabe: 3 × Lenovo ThinkPad T14 Gen 5 (3.147,00 € netto)",
  "type": "approval"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/tasks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/answer' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"comment":"Passt, bitte beim Stammlieferanten bestellen.","outcome":"approved","values":{"kostenstelle":"4100 Vertrieb"}}'
```

# Catalog

## The actions, events and node kinds flows can use (tenant:flows:read|write|admin)

`GET /api/flows/v1/catalog`

Module: Flows · operationId: `getFlowsCatalog` · Tag: Catalog · Auth: access token (`Authorization: Bearer <accessToken>`)

Every module's flows manifest (its `x-flows` actions with parameter and answer schemas, its events with payload
schemas), the built-in node kinds, the expression namespaces and the functions of the expression language.

### Responses

- **200** The catalogue (`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`)

Fields of the 200 answer:

- `functions` (array of string, required): Functions of the expression language
- `kinds` (array of object, required): Every node kind with its default ports (a node's own ports – switch cases, parallel branches, the task type – come with each validation)
  - `fields` (array of KindField, required): The kind's fields besides the common ones
    - `path` (string, required): Dotted below the node or trigger
    - `type` (string, required): The editor: `expression` (expr-lang, no braces), `template` / `longtemplate` (text with `{{ }}`), `text`, `enum` (one of `options`), `number`, `bool`, `duration` (`30s`, `2h`, `3d`), `list`, `people` (a list of references: `person:<email>`, `employee:<id>`, `group:<id>`, `role:<id>`, `manager:<email or employee id>` – HR ids – or an expression; a mail's `to` also takes a plain address and `channel:<id>`, a comms channel of kind Teams or webhook), `channel:teams` / `channel:email` (the id of a comms channel of that medium), `map`, `cases`, `form`, `escalation`, `aifields`. Clients treat an unknown type as JSON.
    - `options` (array of string): The values of an enum – exactly what the validator accepts
    - `when` (object): The field applies only while the sibling field has one of the values
      - `equals` (array of string): Values of the sibling field for which this field applies
      - `field` (string): The sibling field
  - `name` (string, required): Node kind
  - `ports` (array of string, required): Default output ports
  - `retry` (boolean, required): Whether `timeout` and `retry` apply (other kinds are never retried)
- `modules` (array of Manifest, required): Every module's flows manifest
  - `events` (array of object): The events flows can start on, with their payload schemas
  - `inline` (object): What the module's own, immediate automations do besides its `inline` actions (absent: nothing)
    - `mail` (boolean): They send mail immediately
    - `manualEvent` (string): The event whose payload a manual start carries (absent: nothing is started by hand)
  - `module` (string): Module name
  - `nodes` (array of object): The actions; `inline: true` marks one the module also runs immediately in its own automations
  - `revision` (string): Revision of the manifest (changes with the module's spec)
  - `version` (integer): Manifest format version
- `namespaces` (array of string, required): Namespaces expressions can read
- `retryFields` (array of KindField): `timeout` and `retry.*` of the kinds with `retry`
  - `path` (string, required): Dotted below the node or trigger
  - `type` (string, required): The editor: `expression` (expr-lang, no braces), `template` / `longtemplate` (text with `{{ }}`), `text`, `enum` (one of `options`), `number`, `bool`, `duration` (`30s`, `2h`, `3d`), `list`, `people` (a list of references: `person:<email>`, `employee:<id>`, `group:<id>`, `role:<id>`, `manager:<email or employee id>` – HR ids – or an expression; a mail's `to` also takes a plain address and `channel:<id>`, a comms channel of kind Teams or webhook), `channel:teams` / `channel:email` (the id of a comms channel of that medium), `map`, `cases`, `form`, `escalation`, `aifields`. Clients treat an unknown type as JSON.
  - `options` (array of string): The values of an enum – exactly what the validator accepts
  - `when` (object): The field applies only while the sibling field has one of the values
    - `equals` (array of string): Values of the sibling field for which this field applies
    - `field` (string): The sibling field
- `triggers` (array of object): Every trigger kind with its fields
  - `fields` (array of KindField, required): Fields of the trigger kind
    - `path` (string, required): Dotted below the node or trigger
    - `type` (string, required): The editor: `expression` (expr-lang, no braces), `template` / `longtemplate` (text with `{{ }}`), `text`, `enum` (one of `options`), `number`, `bool`, `duration` (`30s`, `2h`, `3d`), `list`, `people` (a list of references: `person:<email>`, `employee:<id>`, `group:<id>`, `role:<id>`, `manager:<email or employee id>` – HR ids – or an expression; a mail's `to` also takes a plain address and `channel:<id>`, a comms channel of kind Teams or webhook), `channel:teams` / `channel:email` (the id of a comms channel of that medium), `map`, `cases`, `form`, `escalation`, `aifields`. Clients treat an unknown type as JSON.
    - `options` (array of string): The values of an enum – exactly what the validator accepts
    - `when` (object): The field applies only while the sibling field has one of the values
      - `equals` (array of string): Values of the sibling field for which this field applies
      - `field` (string): The sibling field
  - `name` (string, required): Trigger kind (one of `event`, `schedule`, `manual`, `webhook`)

Example 200 answer:

```json
{
  "functions": [
    "len",
    "lower",
    "upper",
    "trim",
    "join",
    "filter",
    "map",
    "first",
    "last",
    "now",
    "date",
    "duration"
  ],
  "kinds": [
    {
      "fields": [
        {
          "path": "deadline.after",
          "type": "duration"
        }
      ],
      "name": "human_task",
      "ports": [
        "approved",
        "rejected",
        "timeout",
        "error"
      ],
      "retry": false
    },
    {
      "fields": [
        {
          "path": "action",
          "type": "text"
        }
      ],
      "name": "action",
      "ports": [
        "success",
        "error"
      ],
      "retry": true
    }
  ],
  "modules": [
    {
      "events": [
        {
          "actorKind": "person",
          "group": "Tickets",
          "label": {
            "de": "Ticket angelegt",
            "en": "Ticket created"
          },
          "requires": [
            "desk:read"
          ],
          "schema": {
            "properties": {
              "itemId": {
                "type": "string"
              },
              "number": {
                "type": "string"
              },
              "priority": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "type": "desk.item.created"
        }
      ],
      "inline": {
        "mail": true,
        "manualEvent": "desk.item.updated"
      },
      "module": "desk",
      "nodes": [
        {
          "access": "read",
          "category": "Tickets",
          "description": {
            "de": "Ein Ticket mit seinen Feldern.",
            "en": "A ticket with its fields."
          },
          "idempotency": "natural",
          "key": "desk.item.get",
          "label": {
            "de": "Ticket lesen",
            "en": "Read ticket"
          },
          "method": "GET",
          "operationId": "getItem",
          "paramIn": {
            "ref": "path"
          },
          "params": {
            "properties": {
              "ref": {
                "type": "string"
              }
            },
            "required": [
              "ref"
            ],
            "type": "object"
          },
          "pathTemplate": "/api/desk/v1/items/{ref}",
          "permission": [
            "desk:read",
            "desk:write",
            "desk:admin"
          ]
        }
      ],
      "revision": "9f3c1a7e",
      "version": 1
    }
  ],
  "namespaces": [
    "trigger",
    "nodes",
    "vars",
    "item",
    "loop",
    "error",
    "run"
  ],
  "retryFields": [
    {
      "path": "timeout",
      "type": "duration"
    },
    {
      "path": "retry.attempts",
      "type": "number"
    }
  ],
  "triggers": [
    {
      "fields": [
        {
          "path": "cron",
          "type": "text"
        },
        {
          "path": "timezone",
          "type": "text"
        },
        {
          "options": [
            "skip",
            "once"
          ],
          "path": "catchup",
          "type": "enum"
        }
      ],
      "name": "schedule"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/catalog' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## The templates a new flow or immediate automation can start from (tenant:flows:read|write|admin)

`GET /api/flows/v1/templates`

Module: Flows · operationId: `listFlowTemplates` · Tag: Catalog · Auth: access token (`Authorization: Bearer <accessToken>`)

Ready-made automations in display order (category, then registry order). Without parameters the list holds
the tenant-wide flows: pass a template's `key` as `template` (and the values of its `params`) to
`POST /api/flows/v1/flows`. `profile` and `scope` pick another list – what the settings of a forge project or
a desk space offer: `scope` is the *kind* of scope a template is made for (never one scope), `profile=inline`
the immediate automations of the module that owns that kind. An inline template never becomes a flow: render
it (`POST /api/flows/v1/templates/{key}/render`) and create the automation in its module. `available` is false
while a module the template uses is not offered by the catalogue (for an inline template: while its module
does not declare the template's actions as immediate); creating it would give a draft with validation errors.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `profile` | query | string |  | Where the templates run: `durable` (flows, the default) or `inline` (immediate automations of a module); anything else is `400 invalid`, field `profile` (one of `durable`, `inline`; default `"durable"`) |
| `scope` | query | string |  | The kind of scope the templates are made for: `desk:space` or `forge:project`; without it the tenant-wide templates. Anything else – also one scope with its id – is `400 invalid`, field `scope` (one of `desk:space`, `forge:project`) |

### Responses

- **200** The templates (`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`)

Fields of the 200 answer:

- `items` (array of FlowTemplate, required): The templates
  - `available` (boolean, required): False while a module the template uses is not offered by the catalogue
  - `category` (string, required): Category the template is listed under (one of `support`, `sales`, `people`, `operations`, `development`, `general`)
  - `description` (LocalizedText, required)
    - `de` (string, required): German text
    - `en` (string, required): English text
  - `key` (string, required): Template key; pass it as `template` to createFlow
  - `modules` (array of string, required): The modules whose actions and events the template uses
  - `name` (LocalizedText, required)
    - `de` (string, required): German text
    - `en` (string, required): English text
  - `params` (array of FlowTemplateParam, required): What the person fills in before creating it, in display order (empty: nothing)
    - `key` (string, required): Key of the value in `params`
    - `label` (LocalizedText, required)
    - `required` (boolean, required): The value must not be empty. Left out, a required parameter takes its `default`; one without a `default` must be sent. Every parameter is required or has a `default`.
    - `type` (string, required): The input and the JSON type of the value: `text` (string, at most 4000 characters), `number`, `bool`, `enum` (one `options[].value`), `email` (one address), `people` (always a list: `person:<email>`, `employee:<id>`, `group:<id>`, `role:<id>`, `manager:<email or id>` – the people references of a mail node with HR ids –, a plain address, or `creator` – the person creating it). The pickers hand over a key or name of the tenant's configuration as a string of at most 200 characters: `desk_space` (space key), `desk_priority` (priority key), `desk_type` (type key), `desk_team` (team key), `desk_status` (status key of a ticket workflow), `desk_label` (label name), `forge_project` (project key), `forge_label` (label name), `forge_type` (item type key), `forge_status` (status key). `duration` is a time span as a string: a whole number of hours or days, `4h` or `2d` (pattern `^[1-9][0-9]{0,3}[hd]$`, at most 360 days; a day is 24 hours) – nothing else is accepted, and it is always required. (one of `text`, `number`, `bool`, `enum`, `email`, `people`, `desk_space`, `desk_priority`, `desk_type`, `desk_team`, `desk_status`, `desk_label`, `forge_project`, `forge_label`, `forge_type`, `forge_status`, `duration`)
    - `default` (any): The value used when none is sent, of the parameter's type (a list for `multiple` and `people`)
    - `help` (object): What to enter (absent when the label says it)
    - `multiple` (boolean): The value is a list of values of the type, at most 50 (enum and the pickers; `people` always is a list)
    - `options` (array of object): The choices of an `enum`
      - `label` (LocalizedText, required)
      - `value` (string, required): The value to send
  - `profile` (string, required): `durable`: a flow, created with `POST /api/flows/v1/flows`. `inline`: an immediate automation of the module in `modules` – rendered here, created there. (one of `durable`, `inline`)
  - `triggers` (array of string, required): The kinds of the template's triggers
  - `hint` (object): What to adjust after creating the flow that no parameter covers (absent: nothing)
  - `scope` (string): The kind of scope the template is made for (absent: tenant-wide) (one of `desk:space`, `forge:project`)
- `total` (integer, required): Number of items

Example 200 answer:

```json
{
  "items": [
    {
      "available": true,
      "category": "support",
      "description": {
        "de": "Bei jedem neuen Ticket mit einer der gewählten Prioritäten fasst die KI die Meldung zusammen und Sie bekommen eine Mail.",
        "en": "For every new ticket with one of the chosen priorities the AI summarises it and you get an email."
      },
      "key": "kritische-tickets-melden",
      "modules": [
        "desk"
      ],
      "name": {
        "de": "Kritische Tickets melden",
        "en": "Report critical tickets"
      },
      "params": [
        {
          "default": [
            "hoch",
            "kritisch"
          ],
          "key": "priorities",
          "label": {
            "de": "Prioritäten",
            "en": "Priorities"
          },
          "multiple": true,
          "required": false,
          "type": "desk_priority"
        },
        {
          "default": [
            "creator"
          ],
          "key": "recipients",
          "label": {
            "de": "Empfänger",
            "en": "Recipients"
          },
          "multiple": true,
          "required": true,
          "type": "people"
        }
      ],
      "profile": "durable",
      "triggers": [
        "event"
      ]
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/templates' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Fill a template with parameter values and get its definition, without creating anything (tenant:flows:read|write|admin)

`POST /api/flows/v1/templates/{key}/render`

Module: Flows · operationId: `renderFlowTemplate` · Tag: Catalog · Auth: access token (`Authorization: Bearer <accessToken>`)

Returns the definition (YAML) a template gives for `name`, `key` and the values of its `params`; nothing is
stored. Use it to preview a flow, and to create an immediate automation from an inline template: post the
YAML to the automation routes of the module that owns it (forge: `POST /api/forge/v1/projects/{key}/automations`),
which validates and stores it under its own rules. Parameter values are data: each is inserted as one YAML
value (a scalar, or a list of scalars) or as a literal of the expression language, so a value never adds keys,
nodes, triggers or expressions to the definition. A parameter left out takes its `default`; an unknown
parameter, a missing required one, a value of the wrong type or an enum value outside the options is
`400 invalid` with the field `params.<key>`. A template whose recipients default to the caller needs a caller
with an e-mail address (`400 invalid`, field `template`). The pickers' values (a project key, a label name,
a space key) are not checked here – the definition's validation and the first run do.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | The key of a template from `GET /api/flows/v1/templates` |

### Request body

`application/json` (required)

- `name` (string, required): The name of the new flow or automation (max length 200)
- `key` (string): Lower case letters, digits and dashes; default derived from the name (max length 63)
- `params` (FlowTemplateValues): The values of a template's parameters by key: a string, a number, a boolean or a list of strings, as the parameter's `type` says.

Example:

```json
{
  "name": "Fehler kennzeichnen",
  "params": {
    "label": "bug",
    "type": "fehler"
  }
}
```

### Responses

- **200** The definition (`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`)

Fields of the 200 answer:

- `yaml` (string, required): The definition with every placeholder filled in

Example 200 answer:

```json
{
  "yaml": "schemaVersion: 1\nkey: fehler-kennzeichnen\nname: \"Fehler kennzeichnen\"\ndescription: \"Setzt ein Label an jedes neue Element eines Typs.\"\ntriggers:\n  - {id: angelegt, kind: event, event: forge.item.created, filter: \"trigger.data.typeKey == \\\"fehler\\\"\"}\nnodes:\n  kennzeichnen:\n    kind: action\n    name: Label setzen\n    action: forge.item.add_label\n    params:\n      key: \"{{ trigger.data.projectKey }}\"\n      number: \"{{ trigger.data.number }}\"\n      label: \"bug\"\nedges:\n  - angelegt -\u003e kennzeichnen\n"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/templates/forge-typ-kennzeichnen/render' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Fehler kennzeichnen","params":{"label":"bug","type":"fehler"}}'
```

