WebSocket Events
Atomic broadcasts realtime events over a WebSocket endpoint:
ws://localhost:8080/ws?token=<token>Use wss:// when Atomic is behind HTTPS.
Authentication
Section titled “Authentication”The WebSocket token is passed as a query parameter:
/ws?token=<your-token>Use a dedicated token for long-running integrations where possible.
Event Envelope
Section titled “Event Envelope”Server events are JSON objects with a type field:
{ "type": "EmbeddingComplete", "atom_id": "uuid"}The React frontend normalizes these to kebab-case event names, but raw WebSocket clients receive the original server event shape.
Pipeline Events
Section titled “Pipeline Events”Raw server event types:
EmbeddingStartedEmbeddingCompleteEmbeddingFailedTaggingCompleteTaggingFailedTaggingSkippedBatchProgressPipelineQueueStartedPipelineQueueProgressPipelineQueueCompletedEventsLagged
Frontend-normalized names include embedding-started, embedding-complete, tagging-complete, batch-progress, pipeline-queue-started, pipeline-queue-progress, pipeline-queue-completed, and server-events-lagged.
Atom Events
Section titled “Atom Events”AtomCreatedAtomUpdated
These are emitted when atoms are created or updated through API, bulk create, or MCP paths that broadcast lifecycle events.
Report findings ride this same channel: a successful scheduled or manual report run broadcasts AtomCreated with the new finding atom (which has kind = 'report'). The UI filters on kind to react only to findings when that matters.
Import and Ingestion Events
Section titled “Import and Ingestion Events”ImportProgressIngestionFetchStartedIngestionFetchCompleteIngestionFetchFailedIngestionSkippedIngestionCompleteIngestionFailedFeedPollCompleteFeedPollFailed
These power progress UI for Obsidian import, URL ingestion, browser clipping, iOS share ingestion, and feed polling.
Chat Events
Section titled “Chat Events”ChatStreamDeltaChatToolStartChatToolCompleteChatCompleteChatCanvasActionChatError
The message send endpoint returns a final response, but the UI receives streaming deltas and tool events over WebSocket.
Dashboard Events
Section titled “Dashboard Events”DashboardFeaturedChanged
Emitted when the per-database featured-report pointer changes — explicitly via PUT /api/dashboard/featured-report, or implicitly when the featured report is deleted (the backend auto-clears the pointer in that case). The payload carries the new report_id (or null when cleared) so the dashboard widget and any open report detail-view star can refetch without polling. Frontend-normalized name: dashboard-featured-changed.
Lag Handling
Section titled “Lag Handling”The server uses a broadcast channel. If a client falls behind, it can receive an EventsLagged event with the number of skipped events. Clients should reconcile state by refetching the relevant resource — atoms, pipeline status, or the latest finding from the featured report.