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.
Discovery needs no key. Ratings and market analysis are Pro.
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.