## Check an automation's definition without storing it (desk access; a space the caller sees)

`POST /api/desk/v1/automations/validate`

Module: Desk · operationId: `validateDeskAutomation` · Tag: Automation · Auth: access token (`Authorization: Bearer <accessToken>`)

Scope `tenant`: everyone with desk access. Scope `space:<id>`: whoever sees the space (a space the caller does not see, or an unknown one, is 404; a malformed scope 400 `scope`). Validates the YAML with the inline profile against desk's catalogue and answers the findings (the same codes, paths and positions as flows) and the ports of every node. `needsDurable` says that the definition is fine but for parts only a flow in the background can run.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | string | yes | Whose automations: `tenant` (every space) or `space:<space id>` |

### Request body

`application/json` (required)

- `yaml` (string, required)

Example:

```json
{
  "yaml": "schemaVersion: 1\nkey: vip-hoch\nname: VIP-Tickets mindestens hoch\ntriggers:\n  - { id: label, kind: event, event: desk.item.updated, filter: '\"vip\" in trigger.data.labels' }\nnodes:\n  hochstufen:\n    kind: action\n    action: desk.item.update\n    params: { ref: \"{{ trigger.data.itemId }}\", priority: hoch }\n    retry: { attempts: 3 }\nedges:\n  - label -\u003e hochstufen\n"
}
```

### Responses

- **200** The findings (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `diagnostics` (array of AutomationDiagnostic, required): Findings of the check (errors and warnings)
  - `code` (string, required): Stable code, e.g. `unknown_action`, `missing_param`, `expression`, `needs_durable`, `inline_ignored`
  - `message` (string, required): What is wrong
  - `severity` (string, required): Errors keep the automation from being enabled (one of `error`, `warning`)
  - `col` (integer): Column in the YAML definition
  - `line` (integer): Line in the YAML definition
  - `nodeId` (string): Node the finding refers to (empty: the whole definition)
  - `params` (object): `needs_durable`: `reason` (trigger, kind, action, foreign_action, foreign_event, recipient, too_many_nodes)
  - `path` (string): Dotted path in the definition
- `needsDurable` (boolean, required): A finding is `needs_durable`: the definition runs only as a flow in the background
- `permissions` (array of array of string, required): The any-of permission groups a flow with this definition would need
- `ports` (object, required): The output ports of every node that parsed, by node id (the builder's handles)
- `profile` (string, required): The profile the definition was checked with (one of `inline`)
- `valid` (boolean, required): No finding is an error

Example 200 answer:

```json
{
  "diagnostics": [
    {
      "code": "inline_ignored",
      "col": 7,
      "line": 12,
      "message": "Die Option „retry“ gilt nur für Flows im Hintergrund und wird hier ignoriert.",
      "nodeId": "hochstufen",
      "path": "nodes.hochstufen.retry",
      "severity": "warning"
    }
  ],
  "needsDurable": false,
  "permissions": [
    [
      "desk:write"
    ]
  ],
  "ports": {
    "hochstufen": [
      "main",
      "error"
    ]
  },
  "profile": "inline",
  "valid": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/automations/validate?scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"yaml":"schemaVersion: 1\nkey: vip-hoch\nname: VIP-Tickets mindestens hoch\ntriggers:\n  - { id: label, kind: event, event: desk.item.updated, filter: '\''\"vip\" in trigger.data.labels'\'' }\nnodes:\n  hochstufen:\n    kind: action\n    action: desk.item.update\n    params: { ref: \"{{ trigger.data.itemId }}\", priority: hoch }\n    retry: { attempts: 3 }\nedges:\n  - label -\u003e hochstufen\n"}'
```
