--- name: fanfare-api.fly.dev description: fanfare-api.fly.dev provides read-only reference and schedule data for five major North American sports leagues: NBA, WNBA, NFL, NHL, and MLB. It returns team metadata, player rosters, game schedules, current standings, and (for MLB) venue details. It does not provide live play-by-play, historical season archives, or player statistics. host: fanfare-api.fly.dev --- # fanfare-api.fly.dev Fanfare API is a multi-sport data host covering NBA, WNBA, NFL, NHL, and MLB. It serves agents that need to resolve team or player identifiers, retrieve game schedules for a given date, or look up current standings. Its coverage is broad across leagues but shallow in depth — roster and schedule snapshots rather than deep analytics or streaming data. ## When to use this host Use fanfare-api.fly.dev when an agent needs team metadata, player roster lookups, game schedules by date, or current standings for NBA, WNBA, NFL, NHL, or MLB. It is the right choice for resolving team IDs or abbreviations, checking today's game slate, or answering current-season standings questions. Do not use it for: live in-game scores or play-by-play (no streaming feed exists); historical standings or stats from past seasons; player performance statistics (all stats fields return null); NFL or NHL player rosters (no player endpoints exist for those leagues); or venue data outside MLB. For live sports data, seek a dedicated real-time sports API. For player statistics or historical records, use a sports analytics platform with deeper data coverage. ## Capabilities ### Team Reference Lookup Returns canonical team lists with IDs, names, abbreviations, and city data for each league. These are foundational lookups used to resolve team identifiers before querying schedules or standings. - **`fetch-nba-teams`** — Returns a list of all 30 NBA teams with id, name, full name, abbreviation, and city for each team. - **`fetch-wnba-teams`** — Returns the full list of WNBA teams with IDs, names, abbreviations, and city information from the Fanfare API. - **`fetch-nfl-teams`** — Returns a list of all 32 NFL teams with their id, name, full name, abbreviation, and city, plus request metadata including sport, league, and retrieval timestamp. - **`fetch-nhl-teams`** — Returns a list of all NHL teams (current and historical) with id, name, full_name, abbreviation, and available standings fields from the Fanfare API. - **`fetch-mlb-teams`** — Returns the current list of all MLB teams with their ID, name, abbreviation, city, and league/division assignment. ### Player Roster Lookup Returns full player rosters across leagues with player IDs, names, positions, jersey numbers, and team assignments. Stats fields are null; these are identity and assignment records only. - **`fetch-nba-players`** — Returns a full roster of NBA players across all teams, including player IDs, names, positions, jersey numbers, and team IDs. - **`fetch-wnba-players`** — Returns a full roster of WNBA players across all teams, including player ID, name, position, jersey number, and team ID. - **`fetch-mlb-players`** — Returns a full roster of active MLB players including player ID, name, position, jersey number, team ID, batting/throwing hand, and status for a given sport ID. ### Game Schedules Returns game schedule entries for a given date across NBA, WNBA, NHL, and MLB, including matchup details, game status, venue, and scores for past or upcoming games. Not a live feed. - **`fetch-nba-schedule`** — Returns NBA game schedule data for a given date, including team names, game status, venue details, and scores. - **`fetch-wnba-schedule`** — Returns WNBA game schedule data for a given date, including game IDs, team details, status, scores, and venue information. - **`fetch-nhl-schedule`** — Returns NHL game schedule entries for a given date or the current period, including team names, game status, venue, and score data. - **`fetch-mlb-schedule`** — Returns MLB game schedule data for a given date and/or team, including game status, scores, home/away teams, and venue details. ### Current Standings Returns current season standings for WNBA, MLB, NHL, and NFL, including win-loss records, points or percentages, and division or conference rankings. Current season only, not historical. - **`fetch-wnba-standings`** — Returns current WNBA league standings including each team's win-loss record and winning percentage, retrieved in real time. - **`fetch-mlb-standings`** — Returns current MLB standings for all teams including win/loss records, division ranks, wildcard ranks, streaks, and home/away splits, optionally filtered by league. - **`fetch-nhl-standings`** — Returns current NHL standings for all teams including wins, losses, OT losses, points, win percentage, and conference/division rankings. - **`fetch-nfl-standings`** — Returns current NFL team standings including win/loss records, winning percentage, and wildcard rankings for all teams in the league. ### Venue Details Returns static MLB stadium and venue records including capacity, surface type, roof type, and GPS coordinates. MLB-only; no equivalent exists for other leagues on this host. - **`fetch-mlb-venues`** — Returns MLB venue and stadium records including name, city, capacity, surface type, roof type, and GPS coordinates for all or a specific venue. ## Workflows ### Resolve Team ID Then Fetch Schedule *Use when an agent needs to look up games for a named team but only has a team name or abbreviation, not a numeric team ID (applies to MLB where schedule accepts a teamId parameter).* 1. **`fetch-mlb-teams`** — Retrieve the full MLB team list to map the team name or abbreviation to its numeric team ID. 2. **`fetch-mlb-schedule`** — Query the MLB schedule using the resolved teamId and an optional date to retrieve that team's games. ### Standings With Team Context *Use when an agent needs to present standings results with full team names or city context beyond what the standings response alone provides.* 1. **`fetch-nhl-teams`** — Fetch the canonical NHL team list to build a team ID-to-name mapping. 2. **`fetch-nhl-standings`** — Fetch current NHL standings and enrich team entries using the ID mapping from the previous step. ### MLB Venue Lookup via Schedule *Use when an agent needs detailed venue information (capacity, surface, coordinates) for a stadium hosting a specific MLB game on a given date.* 1. **`fetch-mlb-schedule`** — Retrieve the MLB schedule for the target date to identify the venue ID associated with the game of interest. 2. **`fetch-mlb-venues`** — Fetch full venue details for the specific venue ID returned in the schedule response. ## Skill reference ### `fetch-wnba-schedule` **WNBA Schedule** — Returns WNBA game schedule data for a given date, including game IDs, team details, status, scores, and venue information. *Use when:* Use when an agent needs to retrieve WNBA game listings for a specific date or the current day, including matchup details, tip-off times, game status, and venue information. *Not for:* Do not use for real-time in-game play-by-play or live score updates; this endpoint returns scheduled and completed game metadata, not a live game feed. **Inputs:** - `date` (string) — Date for which to retrieve the WNBA schedule, in YYYY-MM-DD format. If omitted, returns the schedule for the current date. **Returns:** Returns a list of WNBA games for the requested date, each with game ID, UTC tip-off time, scheduled/live/final status, home and away team details (name, abbreviation, city), current score, and venue name and location. **Example:** `GET https://fanfare-api.fly.dev/wnba/schedule?date=2026-05-17` --- ### `fetch-nhl-teams` **NHL Teams Lookup** — Returns a list of all NHL teams (current and historical) with id, name, full_name, abbreviation, and available standings fields from the Fanfare API. *Use when:* Use when an agent needs a complete roster of NHL team identifiers, abbreviations, or full names to resolve team references, build dropdowns, or map team IDs for downstream NHL data queries. *Not for:* Do not use for live standings, scores, or game schedules — this endpoint returns team metadata only, and standings fields (wins, losses, points, etc.) are null in the current response. **Returns:** Returns a JSON object with request metadata and a data array of NHL team records (current and historical), each with id, name, full_name, abbreviation, and null standings fields. **Example:** `GET https://fanfare-api.fly.dev/nhl/teams` --- ### `fetch-wnba-standings` **WNBA Standings** — Returns current WNBA league standings including each team's win-loss record and winning percentage, retrieved in real time. *Use when:* Use when an agent needs the current WNBA standings, such as to answer questions about team records, league rankings, or season performance across all WNBA franchises. *Not for:* Do not use for historical standings from past seasons, individual player statistics, or game schedules; use a dedicated historical or schedule endpoint instead. **Returns:** Returns an array of all WNBA teams with their current wins, losses, and winning percentage, plus request metadata and empty warnings/errors arrays. **Example:** `GET https://fanfare-api.fly.dev/wnba/standings` --- ### `fetch-wnba-teams` **WNBA Teams Lookup** — Returns the full list of WNBA teams with IDs, names, abbreviations, and city information from the Fanfare API. *Use when:* Use when an agent needs a reference list of all WNBA teams — including team IDs, abbreviations, and city names — to resolve team identifiers or populate a team selector before querying other WNBA endpoints. *Not for:* Do not use for real-time standings, win/loss records, or conference/division rankings; those fields are not populated in this response. Not suitable for NBA or other leagues. **Returns:** Returns a list of 15 WNBA teams, each with a numeric string id, short name, full_name, abbreviation, and city; conference, division, record, and rank fields are present but null. **Example:** `GET https://fanfare-api.fly.dev/wnba/teams` --- ### `fetch-wnba-players` **WNBA Player Data** — Returns a full roster of WNBA players across all teams, including player ID, name, position, jersey number, and team ID. *Use when:* Use when an agent needs a complete list of current WNBA players with their profile metadata such as position, jersey number, and team assignment. *Not for:* Do not use for per-player statistics or game-level data; the stats field is null in the response and this endpoint does not return performance metrics. **Returns:** Returns a JSON object with request metadata and a data array of WNBA player profiles including player ID, full name, position, jersey number, team ID, and a null stats field. **Example:** `GET https://fanfare-api.fly.dev/wnba/players` --- ### `fetch-nba-schedule` **NBA Schedule** — Returns NBA game schedule data for a given date, including team names, game status, venue details, and scores. *Use when:* Use when an agent needs to look up upcoming or past NBA games for a specific date, including matchup details, game status, venue, and score information. *Not for:* Do not use for real-time in-game play-by-play or live score updates; this is a schedule snapshot, not a streaming feed. **Inputs:** - `date` (string) — Date for which to retrieve the NBA schedule. Format not specified in schema; ISO 8601 date string (YYYY-MM-DD) is recommended. **Returns:** Returns a JSON object with request metadata and a data array of NBA game entries, each including team details, game status, venue info, and current score (null if not yet played). **Example:** `GET https://fanfare-api.fly.dev/nba/schedule?date=2026-05-18` --- ### `fetch-nba-players` **NBA Player Lookup** — Returns a full roster of NBA players across all teams, including player IDs, names, positions, jersey numbers, and team IDs. *Use when:* Use when an agent needs a complete list of current NBA players with their identifiers, positions, jersey numbers, and team assignments for lookup, filtering, or downstream processing. *Not for:* Do not use for real-time game scores, standings, or player statistics — this endpoint returns player roster data with null stats fields, not live or historical stat lines. **Returns:** Returns a JSON object with request metadata and a data array of NBA player records, each containing player ID, full name, position (G/F/C), jersey number, team ID, and a null stats field. **Example:** `GET https://fanfare-api.fly.dev/nba/players` --- ### `fetch-mlb-players` **MLB Players** — Returns a full roster of active MLB players including player ID, name, position, jersey number, team ID, batting/throwing hand, and status for a given sport ID. *Use when:* Use when an agent needs a complete list of active MLB players with identifiers, positions, team assignments, and handedness — for example to look up a player's team, position, or jersey number. *Not for:* Do not use for per-player statistics or historical stats; the stats field is null in responses. Not suitable for real-time game or play-by-play data. **Inputs:** - `sportId` (integer) — Numeric sport identifier. Defaults to 1 (MLB baseball). Change only if targeting a different sport context supported by the API. **Returns:** Returns a JSON object with request metadata and a data array of active MLB player records, each including player ID, full name, position, jersey number, team ID, batting/throwing hand, and a null stats field. **Example:** `GET https://fanfare-api.fly.dev/mlb/players?sportId=1` --- ### `fetch-nhl-schedule` **NHL Schedule** — Returns NHL game schedule entries for a given date or the current period, including team names, game status, venue, and score data. *Use when:* Use when an agent needs to retrieve NHL game listings — upcoming or recently played — including matchup details, game status, venue, and scores for a specific date or the default current schedule window. *Not for:* Do not use for real-time in-game play-by-play or live score updates; this endpoint returns scheduled and completed game records, not a streaming feed. **Inputs:** - `date` (string) — Optional date filter in YYYY-MM-DD format. If omitted, the API returns the default current schedule window. **Returns:** Returns a data array of NHL game objects each with game ID, UTC date, status, home/away team details (name, abbreviation, city), current score, period, clock, and venue name, plus request metadata and empty warnings/errors arrays. **Example:** `GET https://fanfare-api.fly.dev/nhl/schedule?date=2026-05-17` --- ### `fetch-nba-teams` **NBA Teams Lookup** — Returns a list of all 30 NBA teams with id, name, full name, abbreviation, and city for each team. *Use when:* Use when an agent needs a complete roster of NBA teams with their identifiers, abbreviations, and city names, such as to resolve a team name to an ID before querying further NBA data endpoints. *Not for:* Do not use for player rosters, game schedules, scores, or standings — this endpoint returns team metadata only, not game or player data. **Returns:** Returns a JSON object with request metadata and a data array of 30 NBA team objects, each containing id, name, full_name, abbreviation, and city (conference, division, record, and rank fields are currently null). **Example:** `GET https://fanfare-api.fly.dev/nba/teams` --- ### `fetch-mlb-schedule` **MLB Schedule** — Returns MLB game schedule data for a given date and/or team, including game status, scores, home/away teams, and venue details. *Use when:* Use when an agent needs MLB game schedule information for a specific date or team, including game results, scores, and venue details for past, current, or upcoming games. *Not for:* Do not use for non-MLB sports schedules; use a sport-specific endpoint instead. Not suitable for real-time live play-by-play data. **Inputs:** - `date` (string) — Date to filter games by, in ISO 8601 format (YYYY-MM-DD). Defaults to current date if omitted. - `teamId` (integer) — Numeric MLB team ID to filter schedule results to a specific team. **Returns:** Returns a list of MLB games for the requested date/team, each with game ID, status, home/away team details (name, abbreviation, division), final score, and venue name. **Example:** `GET https://fanfare-api.fly.dev/mlb/schedule?date=2026-05-14&teamId=134` --- ### `fetch-mlb-standings` **MLB Standings** — Returns current MLB standings for all teams including win/loss records, division ranks, wildcard ranks, streaks, and home/away splits, optionally filtered by league. *Use when:* Use when an agent needs current MLB team standings data such as division rankings, win-loss records, games back, wildcard positions, or recent streaks for one or both leagues. *Not for:* Do not use for historical standings from past seasons, individual player statistics, or game schedules; use a dedicated historical or player stats API instead. **Inputs:** - `leagueId` (integer) — Numeric MLB league ID to filter standings to a specific league (e.g., American League or National League). Omit to retrieve standings for all teams. **Returns:** Returns a JSON object with request metadata and a data array of team standing entries, each including team identity, win/loss record, home/away splits, last-10 record, current streak, division rank, and wildcard rank. **Example:** `GET https://fanfare-api.fly.dev/mlb/standings?leagueId=103` --- ### `fetch-mlb-teams` **MLB Team List** — Returns the current list of all MLB teams with their ID, name, abbreviation, city, and league/division assignment. *Use when:* Use when an agent needs a reference list of MLB teams including team IDs, abbreviations, cities, and league/division groupings, for example to look up a team ID before querying game schedules or standings. *Not for:* Do not use for live standings, win/loss records, or game scores; those fields are null in this response and require a dedicated standings or scores endpoint. **Inputs:** - `sportId` (integer) — Numeric sport identifier; defaults to 1 (MLB baseball). Change only if querying a different sport context supported by the API. **Returns:** Returns a JSON object with request metadata and a data array of all 30 MLB teams, each with id, name, full_name, abbreviation, city, and league_division; record and standing fields are currently null. **Example:** `GET https://fanfare-api.fly.dev/mlb/teams?sportId=1` --- ### `fetch-mlb-venues` **MLB Venues Lookup** — Returns MLB venue and stadium records including name, city, capacity, surface type, roof type, and GPS coordinates for all or a specific venue. *Use when:* Use when an agent needs static MLB stadium or venue details such as capacity, surface type, roof type, or geographic coordinates — either for all venues or a specific one by ID. *Not for:* Do not use for real-time game schedules, ticket availability, or live event data; use a game or schedule API instead. **Inputs:** - `venueId` (integer) — Optional MLB venue ID to filter results to a single venue. Omit to retrieve all venues. **Returns:** Returns a JSON object with request metadata and a data array of venue records, each including id, name, city, state, country, capacity, surface, roof_type, latitude, and longitude. **Example:** `GET https://fanfare-api.fly.dev/mlb/venues?venueId=22` --- ### `fetch-nhl-standings` **NHL Standings** — Returns current NHL standings for all teams including wins, losses, OT losses, points, win percentage, and conference/division rankings. *Use when:* Use when an agent needs current NHL team standings data including win/loss records, points totals, and conference or division rankings for any NHL team. *Not for:* Do not use for historical standings from past seasons, live game scores, or player-level statistics; use a dedicated historical or game-data API instead. **Returns:** Returns a JSON object with request metadata and a data array of all NHL teams, each with wins, losses, OT losses, points, win percentage, and conference/division rank. **Example:** `GET https://fanfare-api.fly.dev/nhl/standings` --- ### `fetch-nfl-standings` **NFL Standings** — Returns current NFL team standings including win/loss records, winning percentage, and wildcard rankings for all teams in the league. *Use when:* Use when an agent needs current NFL team standings, win/loss records, winning percentages, or wildcard rankings to answer questions about team performance or playoff positioning. *Not for:* Do not use for game schedules, scores, player stats, or historical season standings; use a dedicated game or player stats endpoint instead. **Returns:** Returns a JSON object with a request_id, sport/league metadata, retrieval timestamp, and a data array of all NFL teams with their win/loss/tie records, win percentage, and wildcard/division/conference ranks. **Example:** `GET https://fanfare-api.fly.dev/nfl/standings` --- ### `fetch-nfl-teams` **NFL Teams** — Returns a list of all 32 NFL teams with their id, name, full name, abbreviation, and city, plus request metadata including sport, league, and retrieval timestamp. *Use when:* Use when an agent needs a canonical list of NFL team identifiers, abbreviations, or full names to resolve team references, populate a dropdown, or map team names to IDs for downstream NFL data queries. *Not for:* Do not use for team standings, win/loss records, conference or division breakdowns — those fields are null in the response. Use a dedicated standings or schedule endpoint instead. **Returns:** Returns a JSON object with request metadata and a data array of all 32 NFL teams, each with id, name, full_name, abbreviation, and city; conference, division, and record fields are present but null. **Example:** `GET https://fanfare-api.fly.dev/nfl/teams` ---