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>

Each event is a JSON object with a type field, for example:

id: 1718900000000-0
data: {"type":"source.ingest.queued","scope":{"id":"<source_id>"}, ...}

Common event types:

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). If your Last-Event-ID is older than the oldest retained entry, 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

This replays the message’s events past your last-seen sequence number and tails the rest live. It is backed by the Postgres message_events journal (retained for MESSAGE_EVENTS_RETENTION_DAYS, default 14).

Settings