> For the complete documentation index, see [llms.txt](https://docs.synoptic.com/s/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.synoptic.com/s/websocket/overview.md).

# Overview

Use the WebSocket API to receive stream posts in real time, publish posts to streams you own, or push labelled time-series points for charts.

```url
wss://ws.api.synoptic.com/v1
```

## What You Can Build

* **Realtime readers**: subscribe to posts from streams your reader key can access.
* **Publishing integrations**: publish stream posts from bots, trading systems, scripts, and back-office tools.
* **Custom stream delivery**: receive only the posts that match a customer's configured custom targets.
* **Enriched source posts**: receive `enrichments` (tickers, translations) on source-routed posts. See [Enrichments](/s/integrations/enrichments.md).
* **Realtime charts**: publish labelled numeric points and subscribe to the latest value of each dimension.

## Authentication

Generate API keys from **Settings -> API & Keys**.

* Use a **reader key** for `on-stream-post`.
* Use a **publisher key** for `add-stream-post`.
* Use a **source key** for `source-post`.
* Use a **time-series key** for `time-series`. Reader keys can subscribe to `on-time-series` when they own the series or can read a stream where it is shown.

Pass the key during the WebSocket upgrade as either a query parameter:

```url
wss://ws.api.synoptic.com/v1/on-stream-post?apiKey=<YOUR_READER_KEY>
```

Or as an `x-api-key` header:

```bash
websocat -H="x-api-key: <YOUR_READER_KEY>" wss://ws.api.synoptic.com/v1/on-stream-post
```

## Common Workflows

### Subscribe to posts

Connect to `on-stream-post` to receive posts from streams you follow.

[Subscribe to posts](/s/websocket/subscribe-to-posts.md)

### Publish posts

Connect to `add-stream-post` and send `add-stream-post` messages.

[Publish posts](/s/websocket/publish-posts.md)

### Add source posts

Connect to `source-post` to push structured payloads that are validated against your source's JSON Schema before being routed downstream.

[Add source posts](/s/websocket/add-source-posts.md)

### Publish and read time series

Connect to `time-series` to push labelled numeric points, or to `on-time-series` to subscribe to latest values.

[Time Series](/s/websocket/time-series.md)

## Reconnection

WebSocket clients should reconnect automatically after disconnects, but avoid tight reconnect loops.

Wait a few seconds before reconnecting and add jitter when possible. Rapid repeated reconnects may be rate-limited.

Before a deploy closes existing connections, the server sends an `info` frame, `Server restarting in 30 seconds, please reconnect`, and leaves the socket open. Open the replacement connection during that window. When the window ends, remaining sockets are closed with `Closing connection, please reconnect`, one every 10ms, and any still open after 5 seconds are closed together.

For `on-stream-post`, pass `lastPosts` on reconnect if you need a small catch-up window.

## Message Format

Most subscription events are JSON objects with an `event` and `data` field.

```json
{
  "event": "stream.post.created",
  "data": {
    "streamId": "<STREAM_ID>",
    "text": "New post content"
  }
}
```

Some publishing endpoints, including `source-post` and `time-series`, use flat request or acknowledgement objects. See [Events](/s/websocket/events.md) and the operation-specific guides for the full list of frames you should handle.