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