Server-Sent Events

Comicarr pushes live updates to the browser over Server-Sent Events (SSE).

Endpoint

GET /api/events/stream

Requirement	Detail
Auth	Session cookie (`comicarr_session`) — API key is not accepted
Content type	`text/event-stream`
Keepalive	Server pings ~every 15s; client should reconnect on drop

curl -N -b cookies.txt \
  -H "Accept: text/event-stream" \
  http://localhost:8090/api/events/stream

Each event has an SSE event: name and a JSON data: payload. Sequence id: values may be present for client tracking.

Event catalog

These are the event names the web UI listens for (useServerEvents). Payloads are JSON objects unless noted.

`addbyid`

Emitted while adding a series by ID (progress and completion).

Field	Notes
`status`	`success`, `failure`, or `mid-message-event` (progress; UI ignores for toasts)
`comicid`	Series id
`comicname` / `seriesyear`	Display
`tables`	Cache invalidation hint: `both`, `tables`, `tabs`, or `None`
`message`	Human-readable text

UI: invalidates series queries, shows “Series Added” toast on success, dispatches a comic-added browser event.

`scheduler_message`

Background task finished or failed.

Field	Notes
`status`	`success` / failure
`message`	Required for toast text

`config_check`

Configuration validation / reload signal.

Field	Notes
`config_errors`	Optional list of issues

UI: invalidates the config query cache.

`check_update`

Result of a GitHub / version check.

Field	Notes
`commits_behind`	Number or string
`current_version` / `latest_version`	Optional

UI: toast when updates are available or when up to date.

`search_progress`

Live search progress (often logged only; no toast).

Field	Notes
`current` / `total`	Progress counters
`query`	Search string

`search_complete`

Search finished.

Field	Notes
`result_count`	Number of hits

`storyarc_added`

Story arc add/refresh finished.

Field	Notes
`status`	`success` / error
`storyarcname`	Optional
`message`	Toast body

UI: invalidates story-arc queries.

`ai_activity`

AI feature completed a logged action.

Field	Notes
`feature_type`	Feature key
`action`	Description
`success`	Boolean
`latency_ms`	Optional

UI: invalidates AI activity/status and dashboard queries. Published via the EventBus from the AI activity logger.

`shutdown` / `restart`

Server is stopping or restarting.

Field	Notes
`message`	Human-readable

UI: closes the EventSource and shows a toast. Published from system shutdown/restart routes.

`message` (default channel)

Generic / fallback channel. Same general shape as other payloads (status, message, tables, comicid, …). Used when the event name is omitted or for multi-purpose notifications.

Special data value: END-OF-STREAM closes the client connection.

Delivery model

Backend EventBus (comicarr.app.core.events) fans out to each SSE subscriber queue (max 256 events per subscriber; oldest dropped under overflow).
Many background modules still assign comicarr.GLOBAL_MESSAGES dicts (often with an event field such as addbyid, scheduler_message, check_update, storyarc_added). The UI is built around those names; prefer matching that contract if you extend the app.
Direct EventBus.publish_sync(event_type, payload) is used for at least shutdown, restart, and ai_activity.

Client reconnect

The React client reconnects with exponential backoff (capped) if the stream drops. Integrators should do the same.

Authentication — session cookies
REST API — non-streaming routes
AI Features — AI activity feed in the UI

Server-Sent Events

On this page