## Change notices for open flows pages (tenant:flows:read|write|admin|tasks)

`GET /api/flows/v1/live`

Module: Flows · operationId: `streamFlowsLiveChanges` · Tag: Runs · Auth: access token (`Authorization: Bearer <accessToken>`)

Answers `text/event-stream` (`X-Accel-Buffering: no`, a `: ping` comment every 15 seconds). First a `ready` event
(`{}`), then one `change` event per flow, run or task change the caller may see – with the rules of the read
routes: a flow as `GET /flows/{id}`, a run as `GET /runs/{id}`, a task as `GET /tasks/{id}` (its assignees with
`tenant:flows:tasks`, and who sees its run) – about one to two seconds after the commit; a new stream starts with
the changes of the last 10 seconds. A notice only names what changed (ids, action, state) – never names, data or
definitions; the client reloads through the API. `kind` is `flow` (`action` created, updated, published,
archived, tripped), `run` (`action` started, succeeded, failed, cancelled; `status` of an ended run), `task`
(`action` created, completed; `status`) or `resync` (notices were dropped: reload everything shown). When the
token expires, and after 15 minutes at the latest, the stream ends with a `reconnect` event (`{}`): reconnecting
within 10 seconds loses nothing. At most 10 open streams per person and 500 per tenant and server instance
(429 `rate_limited`).

The notices of a scoped flow (its flow, run and task changes) reach only a stream that names its scope with
`scope` – besides a task's assignees, who always hear of their task. Each named scope is checked once, when
the stream opens: the module that owns it must let the caller view it (`404` otherwise, `503
scope_unavailable` when it cannot answer); the check is repeated at every reconnect, so a changed answer
applies after 15 minutes at the latest. A stream that names scopes still carries the caller's other notices.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | array of string |  | Also stream the changes of this scope's flows (`desk:space:<id>`, `forge:project:<id>`); repeatable, at most 10 (`400 invalid`, field `scope`) |

### Responses

- **200** Event stream (`text/event-stream`)
- **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`)
- **429** Too many open streams (`rate_limited`)
- **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 200 answer:

- `kind` (string, required): What changed (one of `flow`, `run`, `task`, `resync`)
- `action` (string): What happened to it
- `flowId` (string (uuid)): The flow
- `runId` (string (uuid)): The run
- `status` (string): State of an ended run or of a task
- `taskId` (string (uuid)): The task

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/live' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
