Chimely
Api

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.

GET
/v1/inbox/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.

Authorization

SubscriberEnvQ SubscriberHashQ SubscriberIdQ
environment<token>

In: query

subscriber_hash<token>

In: query

subscriber_id<token>

In: query

Header Parameters

Last-Event-ID?string

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"
  }
}