## Change notices for open forge pages (tenant:forge:read)

`GET /api/forge/v1/live`

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

Requires `tenant:forge:read`. Answers `text/event-stream` (`X-Accel-Buffering: no`, a `: ping` comment every
15 seconds). First a `ready` event (`{}`), then one `change` event per item, project or configuration change
of a project the caller sees (the rule of `GET /projects/{key}`: visibility and membership), 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 – never title or content; the client reloads it through the API. `kind` is `item` (`action` =
the history action, `projectId`, `projectKey`, `itemId`, `number`, `ref`), `project` (`action` `saved` with
`projectId` and `projectKey` – also members and repositories –, or `deleted` with `projectId` only, sent to
whoever could see the project before), `config` (`projectId`: reload the project's configuration; no actor) 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. Any other end
means notices may be missing; the client reloads what it shows. At most 10 open streams per person and 500
per tenant and server instance (429 `rate_limited`).

### Responses

- **200** Event stream (`text/event-stream`)
- **401** Error (`application/json`)
- **403** Error (`application/json`)
- **429** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `kind` (string, required): What changed (resync: notices were dropped, reload everything) (one of `item`, `project`, `config`, `milestone`, `iteration`, `resync`)
- `action` (string): item: the history action (created, updated, status_changed, commented, …); project: saved or deleted; milestone: saved, closed, reopened or deleted; iteration: saved, started, closed or deleted
- `itemId` (string (uuid)): Item of an item notice
- `iterationId` (string (uuid)): Iteration of an iteration notice
- `milestoneId` (string (uuid)): Milestone of a milestone notice
- `number` (integer): Number of the item
- `projectId` (string (uuid)): Project of the change
- `projectKey` (string): Key of the project
- `ref` (string): Item reference, e.g. APP-12

### Example request

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