Skip to Content
API ReferenceWebSocket Protocol

WebSocket Protocol

Endpoint: ws://<host>:2900/v1/ws
Transport: RFC 6455
Message format: JSON text frames (server may send gzip-compressed binary frames for larger payloads)

Connection And Authentication

Upgrade

Client opens GET /v1/ws.

Server can reject pre-upgrade for:

  • shutdown mode
  • origin policy failure
  • strict origin check with missing Origin header

Origin policy

Origin allow-list resolution:

  1. security.allowed_ws_origins if non-empty
  2. otherwise security.cors.allowed_origins

Post-connect auth (required)

JSON
{  "type": "authenticate",  "method": "jwt",  "token": "<JWT_TOKEN>"}

Success:

JSON
{  "type": "auth_success",  "user_id": "u_...",  "role": "Dba"}

Failure:

JSON
{  "type": "auth_error",  "message": "Invalid username or password"}

Client Messages

  • authenticate
  • subscribe
  • next_batch
  • unsubscribe

subscribe

JSON
{  "type": "subscribe",  "subscription": {    "id": "orders_live",    "sql": "SELECT * FROM app.orders WHERE status = 'open'",    "options": {      "batch_size": 200,      "last_rows": 100,      "from": 12345    }  }}

next_batch

JSON
{  "type": "next_batch",  "subscription_id": "orders_live",  "last_seq_id": 12345}

unsubscribe

JSON
{  "type": "unsubscribe",  "subscription_id": "orders_live"}

Server Messages

  • auth_success / auth_error
  • subscription_ack
  • initial_data_batch
  • change
  • error

subscription_ack

JSON
{  "type": "subscription_ack",  "subscription_id": "orders_live",  "total_rows": 0,  "batch_control": {    "batch_num": 0,    "has_more": true,    "status": "loading",    "last_seq_id": 12345,    "snapshot_end_seq": 13000  },  "schema": [    {"name":"id","data_type":"BigInt","index":0}  ]}

initial_data_batch

JSON
{  "type": "initial_data_batch",  "subscription_id": "orders_live",  "rows": [{"id":1,"status":"open","_seq":12346}],  "batch_control": {    "batch_num": 0,    "has_more": true,    "status": "loading",    "last_seq_id": 12346,    "snapshot_end_seq": 13000  }}

change

JSON
{  "type": "change",  "subscription_id": "orders_live",  "change_type": "insert",  "rows": [{"id":2,"status":"open","_seq":13001}]}

change_type values:

  • insert
  • update
  • delete

error

JSON
{  "type": "error",  "subscription_id": "orders_live",  "code": "INVALID_SQL",  "message": "..."}

Limits

  • rate_limit.max_subscriptions_per_user (default 10)
  • hard cap per connection: 100
  • security.max_ws_message_size (default 1MB)
  • rate_limit.max_messages_per_sec (default 50)
  • auth timeout: websocket.auth_timeout_secs (default 3)

Error Codes

Common WebSocket protocol/error codes include:

  • AUTH_REQUIRED
  • INVALID_SUBSCRIPTION_ID
  • SUBSCRIPTION_LIMIT_EXCEEDED
  • INVALID_SQL
  • RATE_LIMIT_EXCEEDED
  • MESSAGE_TOO_LARGE
  • UNSUPPORTED_DATA
  • PROTOCOL

For endpoint auth matrix and SQL payload contracts, see HTTP API Reference.

Last updated on
HTTP API ReferenceOverview