---
title: "Subscribe to the live-state SSE stream for an app"
method: GET
path: "/app/{id}/events"
---

# Subscribe to the live-state SSE stream for an app

`GET /app/{id}/events`

## Request

- Base URL: `https://charm.ing`
- URL: `https://charm.ing/app/{id}/events`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - API key in query parameter `t`
  - none

Server-Sent Events stream of `state-changed` notifications. Each event id is `<server-epoch>:<rev>`; the browser `EventSource` replays via `Last-Event-ID` on reconnect, and the server emits a synthetic `state-changed` event with `source: "reconnect-resync"` and `result: null` whenever the client's id belongs to an older epoch or claims an unseen revision. The `overcapacity` event is emitted (and the stream closed) when the per-app subscriber cap is reached. Heartbeats are SSE comment lines (`: ping`) every 15s.

Auth posture is broader than the owner endpoints: appToken, userToken, renderToken (bearer or `?t=` query), or the path-scoped `buildy_sse_<id>` HMAC cookie minted by the `/app/{id}` render-bridge when a render-token rendered the page. The `{}` (no-auth) option in `security` covers the cookie path — OpenAPI cannot model a per-app cookie name as a fixed scheme.

## Query parameters

- `t` string

## Headers

- `Last-Event-ID` string

## Response `200`

Open SSE stream. Frames arrive as `event: state-changed` (or `event: overcapacity`) with a JSON `data:` payload. The stream stays open until the client disconnects, the per-app capacity cap is hit, or the server shuts down.

## Other responses

- `400`: Invalid app id. Error kind: `invalid_id`.
- `401`: Anonymous caller's `buildy_sse_<id>` cookie was once valid but its 1-hour TTL elapsed. Error kind: `sse_cookie_expired` — reload `/app/{id}` so the render-token bridge re-issues a fresh cookie.
- `403`: Caller does not have access to this app.
- `404`: App not found.

---

[API](https://skmtc.dev/charm/apis/charming-api.md) · [All operations](https://skmtc.dev/charm/apis/charming-api/llms.txt) · [OpenAPI document](https://skmtc.dev/charm/apis/charming-api/revisions/a9d06c419b3a?raw)