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