Overview
The BlobHub WebSocket API is the real-time complement to the REST API. It lets clients listen to a session’s event stream — thread items posted, objects written, executions started and ended — without having to poll. Where the REST API answers “what is the current state?”, the WebSocket API answers “what is happening right now?”.Base URL
The WebSocket API is available under:Versioning
The WebSocket API is versioned via a URL prefix. The initial release of the API surface is available under:Authentication
Every WebSocket connection must be authenticated before any listeners can be added. The same token types used by the REST API are accepted here. See Authentication for the exact handshake.Protocol
The WebSocket API uses a simple, symmetric JSON message protocol with a clearly defined connection lifecycle. Two sections cover it end to end:Protocol Overview
The structure of messages exchanged between client and server.
Connection Lifecycle
How connections are opened, authenticated, kept alive, and closed.
Listeners
After initializing, a client adds listeners. A listener is a filter on one session’s event stream; every matching event is pushed to the connection as alistener/event frame, one by one or in batches. A connection holds up to 32 listeners, and they end
with it.
See Server → Listener for the methods, the frames, resuming after a reconnect and the
errors.
When to Use the WebSocket API
Reach for the WebSocket API when you need to:- Push to a client of yours: react to the thread items and objects of a session the moment they are written.
- Drive a live view: keep an interactive UI in step with a session as it changes.
- Catch up by id: reconnect and read what was missed with
after: <last id>and the settle recipe, so a dropped connection loses nothing.

