REST API

REST serves reference data, discovery, and the full historical record. Live events are best consumed over WebSocket or webhooks — the same objects are queryable here after the fact. Every record follows the unified data model. Base URL https://api.firstbuzzer.com; all requests take Authorization: Bearer $FB_API_KEY.

Reference data

Slowly-changing entities you join against. Each carries an external_ids map so the same team or player resolves across every source.

Teams

GET /v1/teams — filter by sport and league. GET /v1/teams/:id for one.

bash

curl "https://api.firstbuzzer.com/v1/teams?sport=baseball&league=mlb" \
  -H "Authorization: Bearer $FB_API_KEY"

json

{
  "data": [
    {
      "id": "team:mlb:bos",
      "sport": "baseball", "league": "mlb",
      "name": "Boston Red Sox", "code": "BOS",
      "venue": "fenway-park",
      "external_ids": { "espn": "2", "mlb_statsapi": "111" }
    }
  ]
}

Players

GET /v1/players — filter by sport, team, season, or search. GET /v1/players/:id for one. In individual sports (tennis, golf, MMA) the player is the competitor.

bash

curl "https://api.firstbuzzer.com/v1/players?team=team:mlb:nyy&season=2026" \
  -H "Authorization: Bearer $FB_API_KEY"

json

{
  "data": [
    {
      "id": "player:mlb:judge",
      "sport": "baseball", "name": "Aaron Judge", "position": "RF",
      "external_ids": { "espn": "33192", "mlb_statsapi": "592450" }
    }
  ]
}

Rosters

GET /v1/teams/:id/roster?season= — the season-scoped team↔player membership (handles trades and transfers historically).

bash

curl "https://api.firstbuzzer.com/v1/teams/team:mlb:nyy/roster?season=2026" \
  -H "Authorization: Bearer $FB_API_KEY"

Venues

GET /v1/venues (filter by sport/league) · GET /v1/venues/:id.

json

{
  "data": [
    { "id": "fenway-park", "name": "Fenway Park", "city": "Boston", "country": "US",
      "geo": { "lat": 42.3467, "lng": -71.0972 } }
  ]
}

Seasons

GET /v1/seasons?league= — the seasons available for a league (and how far the archive goes back).

json

{
  "data": [
    { "id": "mlb_2026", "league": "mlb", "label": "2026",
      "start": "2026-03-26", "end": "2026-11-02" }
  ]
}

Competitions

A competition is the canonical contest — a game, a tennis match, a golf round, an MMA bout — with 1..N competitors (each a team or a player). /v1/games is a convenience alias for team-sport competitions.

List competitions

GET /v1/competitions — filter by sport, league, season, date (today or YYYY-MM-DD), team, player, and status (scheduled, live, final).

bash

curl "https://api.firstbuzzer.com/v1/competitions?league=mlb&season=2026&status=final" \
  -H "Authorization: Bearer $FB_API_KEY"

json

{
  "data": [
    {
      "id": "baseball_mlb_401766",
      "sport": "baseball", "league": "mlb", "season": "2026",
      "date": "2026-06-28", "status": "final", "venue": "fenway-park",
      "competitors": [
        { "entity_type": "team", "entity_id": "team:mlb:bos", "role": "home", "score": 9 },
        { "entity_type": "team", "entity_id": "team:mlb:nyy", "role": "away", "score": 4 }
      ]
    }
  ]
}

Play-by-play

GET /v1/competitions/:id/plays — the official play-by-play (fb.play.v1), attributed to a competitor and, where available, the player. The historical ground truth behind every event.

json

{
  "data": [
    {
      "competition_id": "baseball_mlb_401766", "seq": 142,
      "period": { "unit": "inning", "num": 6, "label": "Top 6" },
      "competitor_id": "team:mlb:nyy", "player_id": "player:mlb:judge",
      "event_type": "run", "points": 1,
      "state": { "home": 4, "away": 5 }, "source": "mlb_statsapi"
    }
  ]
}

Events

GET /v1/games/:id/events — the crowd-confirmed scoring events for a game (live or historical, identical schema). See event types.

json

{
  "data": [
    {
      "id": "evt_8f21", "type": "score", "tier": "confirmed",
      "game_id": "nba_401766", "sport": "basketball", "team": "BOS",
      "event_type": "three", "points": 3, "clock": "Q3 04:12",
      "ts": "2026-06-29T01:14:22.184Z",
      "confidence": { "agreement": 0.94, "reporters": 7, "latency_ms": 820 },
      "schema": "fb.event.v1"
    }
  ]
}

Bulk export

GET /v1/export — the historical archive by league + season (optional from/to, and entity = competitions | plays | events). Large exports stream as newline-delimited JSON with the same schema as the live feed — so a backtest and production read identically.

bash

curl "https://api.firstbuzzer.com/v1/export?league=epl&season=2025&entity=plays" \
  -H "Authorization: Bearer $FB_API_KEY"

Pagination

List endpoints return a cursor when more results exist; pass it back as ?cursor= to page forward. Page size defaults to 100 (?limit= up to 1000).

Questions? Talk to us. Pre-launch — endpoints illustrate the shape of the API.