> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> BlobHub WebSocket API — real-time events across the platform.

## Overview

The **BlobHub WebSocket API** is the real-time complement to the [REST API](/rest-api/introduction). It lets
clients subscribe to live streams of events emitted by the platform — Workflow Execution updates, Session
Events, state changes, and more — 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:

```
wss://realtime.blobhub.io/
```

## Versioning

The WebSocket API is versioned via a URL prefix. The initial release of the API surface is available under:

```
/v1/
```

A full connection URL therefore looks like:

```
wss://realtime.blobhub.io/v1/
```

## Authentication

Every WebSocket connection must be authenticated before any subscriptions can be established. The same token
types used by the REST API are accepted here. See [Authentication](/web-socket/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:

<CardGroup cols={2}>
  <Card title="Protocol Overview" icon="diagram-project" href="/web-socket/protocol/overview">
    The structure of messages exchanged between client and server.
  </Card>

  <Card title="Connection Lifecycle" icon="timeline" href="/web-socket/protocol/lifecycle">
    How connections are opened, authenticated, kept alive, and closed.
  </Card>
</CardGroup>

## Subscriptions

After authenticating, clients subscribe to the event streams they care about. Subscriptions are how the
WebSocket API multiplexes many independent real-time channels over a single connection.

See [Server → Subscription](/web-socket/server/subscription) for the subscription model and the available
event types.

## When to Use the WebSocket API

Reach for the WebSocket API when you need to:

* Observe Workflow **Execution Events** as they are emitted.
* Watch **Session Events** across multiple executions in a long-lived Session.
* React to Blob or Revision state changes without polling.
* Drive an interactive UI that stays in sync with the platform in real time.

For everything else — CRUD on Organizations, Blobs, Revisions, and one-shot operations — use the
[REST API](/rest-api/introduction).