Skip to main content

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:
A full connection URL therefore looks like:

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 a listener/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.
For everything else — CRUD on Organizations, Blobs, Revisions, and one-shot operations — use the REST API. To act on events inside the session instead of in a client, use declared listeners.