WebSocket

Open one socket and subscribe to any combination of sports, leagues, or games. Choose your tier: provisional (first report, tagged — fastest) or confirmed (full consensus).

Connect

const ws = new WebSocket(
  "wss://api.firstbuzzer.com/v1/stream?sport=nba&tier=confirmed",
  { headers: { Authorization: `Bearer ${process.env.FB_API_KEY}` } }
);

ws.onmessage = (m) => {
  const e = JSON.parse(m.data);
  if (e.type === "score") {
    console.log(e.game_id, e.team, "+" + e.points, e.confidence.latency_ms + "ms");
  }
};

Subscribe / unsubscribe at runtime

Send control messages to change what you receive without reconnecting:

{ "action": "subscribe",   "games": ["nba_401766", "nhl_887210"] }
{ "action": "unsubscribe", "sport": "nba" }

Message shape

Event messages match the REST event object exactly (see REST). Control/system frames use a type of ack, error, or heartbeat.

Heartbeats & reconnects

• The server sends a heartbeat every 15s. If you miss two, reconnect.
• On reconnect, pass ?since=<last_event_ts> to backfill anything you missed.
• Use exponential backoff on reconnect; connection count is capped by your plan.