## Check an automation's definition without storing it (tenant:forge:read)

`POST /api/forge/v1/projects/{key}/automations/validate`

Module: Forge · operationId: `validateForgeAutomation` · Tag: Automations · Auth: access token (`Authorization: Bearer <accessToken>`)

Requires `tenant:forge:read` and a project the caller sees. Validates the YAML with the inline profile against forge'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 |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `yaml` (string, required): The definition (YAML of the flow language)

Example:

```json
{
  "yaml": "schemaVersion: 1\nkey: review-erinnerung\nname: Review-Erinnerung\ntriggers:\n  - { id: review, kind: event, event: forge.item.status_changed, filter: 'trigger.data.statusKey == \"review\"' }\nnodes:\n  warten:\n    kind: wait\n    duration: 48h\n  erinnern:\n    kind: action\n    action: forge.comment.add\n    params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", body: Das Review wartet seit zwei Tagen. }\nedges:\n  - review -\u003e warten\n  - warten -\u003e erinnern\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): The findings, errors and warnings
  - `code` (string, required): Stable code, e.g. `unknown_action`, `missing_param`, `expression`, `needs_durable`, `inline_ignored`
  - `message` (string, required): Human-readable text of the finding
  - `severity` (string, required): Errors keep the automation from being enabled (one of `error`, `warning`)
  - `col` (integer): Column in the YAML definition (when known)
  - `line` (integer): Line in the YAML definition (when known)
  - `nodeId` (string): The node the finding is about
  - `params` (object): `needs_durable`: `reason` (trigger, kind, action, foreign_action, foreign_event, recipient, mail_option – a mail node sets `mandatory` or `mailChannel`, which only a tenant flow without scope may –, 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": "needs_durable",
      "col": 3,
      "line": 8,
      "message": "Der Knoten „warten“ kann nicht sofort laufen; als Flow im Hintergrund ist er möglich.",
      "nodeId": "warten",
      "params": {
        "reason": "kind"
      },
      "path": "nodes.warten",
      "severity": "error"
    }
  ],
  "needsDurable": true,
  "permissions": [
    [
      "tenant:forge:write",
      "tenant:forge:admin"
    ]
  ],
  "ports": {
    "erinnern": [
      "main",
      "error"
    ],
    "warten": [
      "main",
      "error"
    ]
  },
  "profile": "inline",
  "valid": false
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations/validate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"yaml":"schemaVersion: 1\nkey: review-erinnerung\nname: Review-Erinnerung\ntriggers:\n  - { id: review, kind: event, event: forge.item.status_changed, filter: '\''trigger.data.statusKey == \"review\"'\'' }\nnodes:\n  warten:\n    kind: wait\n    duration: 48h\n  erinnern:\n    kind: action\n    action: forge.comment.add\n    params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", body: Das Review wartet seit zwei Tagen. }\nedges:\n  - review -\u003e warten\n  - warten -\u003e erinnern\n"}'
```
