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