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.
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.
Briefing Events
Section titled “Briefing Events”BriefingReady
The payload includes db_id and briefing_id.
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, such as atoms, pipeline status, or the latest briefing.