Realtime WebSocket API

The Realtime API exposes a long-lived WebSocket endpoint at /api/v2/realtime for streaming subscription, presence, and event push.

Endpoint

wss://cdn.brlvpn.com/api/v2/realtime

Connections are kept open for the lifetime of the session. Use exponential backoff (initial 500 ms, max 30 s, jitter ±25%) for reconnect attempts.

Authentication

Authentication is performed during the WebSocket upgrade. The client presents a session token; the server validates and either accepts the upgrade (101 Switching Protocols) or rejects with 401 Unauthorized.

Requests to /api/v2/realtime without a valid Upgrade: websocket header or without authentication will receive a structured JSON 401 response pointing back to this documentation page.

Probe (curl)

$ curl -i https://cdn.brlvpn.com/api/v2/realtime
HTTP/2 401
content-type: application/json
{"error":"unauthorized","code":"missing_token","status":401}

Message framing

Messages are binary WebSocket frames. The first byte of each frame indicates the message kind:

Byte	Kind	Direction
`0x01`	SUBSCRIBE	client → server
`0x02`	UNSUBSCRIBE	client → server
`0x10`	EVENT	server → client
`0x20`	PING	bidirectional
`0x21`	PONG	bidirectional
`0xFF`	ERROR	server → client

Subscribe to a topic with an optional filter expression. Topic names are ASCII [a-z0-9._-]+; filter expressions are evaluated server-side.

PING / PONG

The server sends a PING every 30 s of idle. Clients SHOULD respond within 10 s with PONG. Three consecutive missed pongs trigger server-side close.

Status & quotas

Status	Meaning
1000	Normal close
1001	Going away (server restart)
1008	Policy violation (quota / abuse)
1011	Internal error
4401	Auth expired mid-session — reconnect with fresh token

Concurrent connection limit per token: 8. Idle-without-subscribe limit: 60 s. Maximum subscriptions per connection: 64.