Realtime Events & Notifications

DocsGPT pushes realtime updates to the browser over Server-Sent Events (SSE). This is what powers the upload toasts, tool-approval prompts, and other live notifications in the UI. There are two channels:

• User events — GET /api/events: a per-user notification stream (ingestion progress, tool approvals, MCP OAuth completion, …).
• Chat reconnect — GET /api/messages/<message_id>/events: resume an answer stream that was interrupted mid-generation.

User events channel

Open an SSE connection to receive notifications for the authenticated user:

GET /api/events
Accept: text/event-stream
Authorization: Bearer <token>

Authenticate with the session token the web app uses; with AUTH_TYPE unset no token is needed. Personal access tokens are refused on this route. Each record is one id: line and one data: line holding a JSON envelope:

id: 1718900000000-0
data: {"type":"source.ingest.completed","ts":"2026-06-20T16:13:20.000Z","user_id":"alice","topic":"user:alice","scope":{"kind":"source","id":"<source_id>"},"payload":{"source_id":"<source_id>","filename":"guide.pdf","tokens":48213,"operation":"upload","limited":false},"id":"1718900000000-0"}

Between events the stream sends keepalive comments (lines starting with :); SSE clients ignore them.

Event types:

New event types can be added, so ignore types you don’t handle.

Reconnecting and backlog replay

Events are journaled per user in a Redis Stream so a client that reconnects can catch up on what it missed. Send the last id you processed and DocsGPT replays everything after it:

GET /api/events
Last-Event-ID: 1718900000000-0

(You may also pass it as a last_event_id query parameter.) Each delivered event carries its own id:, so your cursor advances as you read. If you fall a long way behind, the snapshot is delivered across several reconnects rather than all at once.

A few bounded behaviors to be aware of:

• The backlog is capped at EVENTS_STREAM_MAXLEN entries (default 1000), and a replay returns only events from the last EVENTS_REPLAY_MAX_AGE_HOURS (default 48). If your Last-Event-ID is older than either limit, or isn’t a valid event id, you receive a backlog.truncated event — reset your cursor and refetch current state.
• Each snapshot is capped at EVENTS_REPLAY_MAX_PER_REQUEST entries per request (default 200); reconnect to continue.
• There is a per-user cap on simultaneous connections (SSE_MAX_CONCURRENT_PER_USER, default 8) and a windowed replay budget. Exceeding either returns HTTP 429 — back off and retry.

Chat answer reconnect

When an answer is streaming and the connection drops, resume it without losing the in-progress generation:

GET /api/messages/<message_id>/events

Send the sequence number of the last event you processed (the id: line of each /stream record) as the Last-Event-ID header or the last_event_id query parameter; without one, the replay starts at the beginning of the message. The route replays the message’s events past that number and tails the rest live, with keepalive comments in between. It is backed by the Postgres message_events journal (retained for MESSAGE_EVENTS_RETENTION_DAYS, default 14).

It takes a session token, or a personal access token with conversations:read or chat:run and no resource restrictions. Only the owner of the message can read it (others get 404), and the connection counts toward the same per-user cap: over SSE_MAX_CONCURRENT_PER_USER it returns HTTP 429.

Settings