API-key-authenticated WebSocket. Pushes one envelope per detected change in `odds_snapshots` or `prop_snapshots` for the subscribed sport. Push latency from DB insert to client frame is ~5 ms via Postgres LISTEN/NOTIFY.
Three forms of API-key delivery accepted on the upgrade request: `?apiKey=` query param, `X-API-Key: ` header, or `Sec-WebSocket-Protocol: apikey.`.
sportKey — Sport key from /v1/sports (e.g. baseball_mlb, basketball_nba, soccer_epl).
Operations
receive
receiveOddsStream
Receive odds updates after sending the upgrade. Frames arrive in this order: one `connected`, one `initial_state`, then zero or more `odds_update` / `heartbeat` / `subscribed` / `unsubscribed` frames.
send
sendOddsCommands
Send commands from client to server over the same WebSocket. Currently `subscribe` (filter to one event_id) and `unsubscribe` (drop the filter).
Messages
connected
Sent once immediately after upgrade. Confirms auth, tier, push mode, and any active query-param filters.
Content-Type:
initial_state
Sent once after `connected`. Carries every active row for the subscribed sport, filtered by any active query params. Honors the `since` resume cursor when within the 60-minute lookback window; falls b
Content-Type:
odds_update
Sent every time a row in `odds_snapshots` or `prop_snapshots` for this sport changes. Payload shape varies by `diff_mode`: when off, every field of the affected row is included; when on, only the chan
Content-Type:
heartbeat
Sent on idle channel timeout (default 30 s for WS, configurable 1-30 s for SSE via `heartbeat_s`). Carries server timestamp; clients should treat absence of any frame for 2x heartbeat as a disconnect
Content-Type:
subscribed
Server acknowledgement of a successful `subscribe` command. Subsequent `odds_update` frames are filtered to the requested event_id only.
Content-Type:
unsubscribed
Server acknowledgement of a successful `unsubscribe` command. Subsequent `odds_update` frames are unfiltered again.
Content-Type:
subscribe
Client-to-server command. Restricts `odds_update` frames to a single event_id.
Content-Type:
unsubscribe
Client-to-server command. Reverts to all-events broadcast.
Content-Type:
stream_status
Reports unresolved Pinnacle fixture families once per subscription generation. It contains no odds. Valid families continue; a fresh current snapshot is required to clear the incomplete-coverage warni
Content-Type:
About AsyncAPI
The AsyncAPI specification describes event-driven APIs the way OpenAPI describes request/response APIs. A channel is the named pipe — a webhook URL, a Kafka topic, a WebSocket route, an MQTT subject — that producers and consumers publish or subscribe to. Each channel carries one or more messages with structured payloads, and an operation declares whether a given party sends or receives on that channel.
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.