SSE hint stream
`text/event-stream` of **hints, not transports**: the client refetches via REST (conditional, ETag) on every hint and on every (re)connect, so missed hints are harmless by construction. Auth via query parameters (browser `EventSource` cannot set headers). Server requirement (tested invariant, not a habit): `subscriber_hash` is scrubbed from access/proxy log lines for this endpoint — query-string credentials otherwise leak into logs. Events (`id:` on every event is an opaque resume token): * `hint` — something changed for this subscriber; refetch list/counts. Debounced server-side (at most one per subscriber per interval). Keep-alive is a comment frame (`: ping`) every 30 seconds, not an event — comment frames are deliberately invisible to EventSource listeners. Unknown future event types must be ignored by clients. Resume: browsers replay `Last-Event-ID` automatically on reconnect; the server answers by emitting an immediate `hint` if anything changed after that token (it does not replay individual missed events — the REST refetch is the recovery mechanism). On graceful shutdown the server sends a `retry:` directive with jitter before closing, so a deploy does not produce a reconnect stampede.
text/event-stream of hints, not transports: the client refetches
via REST (conditional, ETag) on every hint and on every (re)connect, so
missed hints are harmless by construction.
Auth via query parameters (browser EventSource cannot set headers).
Server requirement (tested invariant, not a habit): subscriber_hash
is scrubbed from access/proxy log lines for this endpoint —
query-string credentials otherwise leak into logs.
Events (id: on every event is an opaque resume token):
hint— something changed for this subscriber; refetch list/counts. Debounced server-side (at most one per subscriber per interval).
Keep-alive is a comment frame (: ping) every 30 seconds, not an
event — comment frames are deliberately invisible to EventSource
listeners. Unknown future event types must be ignored by clients.
Resume: browsers replay Last-Event-ID automatically on reconnect; the
server answers by emitting an immediate hint if anything changed
after that token (it does not replay individual missed events — the
REST refetch is the recovery mechanism). On graceful shutdown the
server sends a retry: directive with jitter before closing, so a
deploy does not produce a reconnect stampede.
Authorization
SubscriberEnvQ SubscriberHashQ SubscriberIdQ In: query
In: query
In: query
Header Parameters
Sent automatically by EventSource on reconnect.
Response Body
text/event-stream
application/json
curl -X GET "https://example.com/v1/inbox/stream""id: 01h455vb4pex5vsknk084sn02q\nevent: hint\ndata: {\"reason\":\"notification\"}\n"{
"error": {
"code": "invalid_request",
"message": "string"
}
}Set preferences for a subscriber (admin) PUT
Previous Page
Upsert a subscriber PUT
Subscribers are normally created lazily; this exists for imports. `created_at` may be **backdated** on first create (ignored on update) — it is the knob controlling which historical broadcasts an imported user sees (`broadcast.created_at >= subscriber.created_at`).