{"openapi":"3.1.0","info":{"title":"BALLDONTLIE NHL (BYOK) API","version":"0.1.0","description":"BALLDONTLIE NHL (BYOK) lets an AI assistant read your own BALLDONTLIE NHL data through the BALLDONTLIE NHL API with a key you supply (BALLDONTLIE API key). Read-only: 10 tools (list_teams, get_team, get_team_season_stats, list_players, get_player_season_stats, list_games, get_standings, list_box_scores, get_player_leaders, get_team_leaders). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-balldontlie-nhl.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-balldontlie-nhl/docs"},"termsOfService":"https://connectorbay.com/byok-balldontlie-nhl/terms"},"servers":[{"url":"https://byok-balldontlie-nhl.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-balldontlie-nhl/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_teams":{"post":{"operationId":"list_teams","summary":"List NHL teams with tricode, conference and division, optionally filtered by conference or division. Use for \"Which NHL ","description":"List NHL teams with tricode, conference and division, optionally filtered by conference or division. Use for \"Which NHL teams are in the Atlantic division\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"conference":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Conference name, for example Eastern or Western.","title":"Conference"},"division":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Division name, for example Atlantic.","title":"Division"}},"title":"list_teamsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_team":{"post":{"operationId":"get_team","summary":"Get one NHL team by id. Use for \"Show NHL team 1\".","description":"Get one NHL team by id. Use for \"Show NHL team 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BALLDONTLIE team id, for example 1.","minimum":1,"title":"Id","type":"integer"}},"required":["id"],"title":"get_teamArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_team_season_stats":{"post":{"operationId":"get_team_season_stats","summary":"Get a team's season statistics as name and value pairs for one season. Use for \"What were team 1's season stats in 2025\"","description":"Get a team's season statistics as name and value pairs for one season. Use for \"What were team 1's season stats in 2025\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BALLDONTLIE team id, for example 1.","minimum":1,"title":"Id","type":"integer"},"season":{"description":"Season year, for example 2025.","maximum":2100,"minimum":1900,"title":"Season","type":"integer"},"postseason":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True for playoff statistics, false or omitted for the regular season.","title":"Postseason"}},"required":["id","season"],"title":"get_team_season_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_players":{"post":{"operationId":"list_players","summary":"List or search NHL players by name or team with position, handedness, size and sweater number; 100 per page at most. Use","description":"List or search NHL players by name or team with position, handedness, size and sweater number; 100 per page at most. Use for \"Find the NHL player Connor McDavid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Part of a player name to search for.","title":"Name"},"team_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only players of this team id.","title":"Team Id"},"cursor":{"anyOf":[{"maximum":100000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: the next_cursor value from the previous answer's meta.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Per Page"}},"title":"list_playersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_player_season_stats":{"post":{"operationId":"get_player_season_stats","summary":"Get a player's season statistics as name and value pairs for one season. Use for \"What were player 1's stats in 2025\".","description":"Get a player's season statistics as name and value pairs for one season. Use for \"What were player 1's stats in 2025\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BALLDONTLIE player id, for example 1.","minimum":1,"title":"Id","type":"integer"},"season":{"description":"Season year, for example 2025.","maximum":2100,"minimum":1900,"title":"Season","type":"integer"},"postseason":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True for playoff statistics, false or omitted for the regular season.","title":"Postseason"}},"required":["id","season"],"title":"get_player_season_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_games":{"post":{"operationId":"list_games","summary":"List NHL games filtered by date, season, team or game type with teams, scores, shots on goal, venue, state, period and c","description":"List NHL games filtered by date, season, team or game type with teams, scores, shots on goal, venue, state, period and clock. Use for \"What NHL games were played on 2026-01-15\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only games on this date, YYYY-MM-DD.","title":"Date"},"season":{"anyOf":[{"maximum":2100,"minimum":1900,"type":"integer"},{"type":"null"}],"default":null,"description":"Season year, for example 2025.","title":"Season"},"team_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only games of this team id.","title":"Team Id"},"postseason":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for playoff games only.","title":"Postseason"},"cursor":{"anyOf":[{"maximum":100000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: the next_cursor value from the previous answer's meta.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Per Page"}},"title":"list_gamesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_standings":{"post":{"operationId":"get_standings","summary":"Get NHL standings for a season with points, wins, losses, overtime losses, goals for and against, home and road record a","description":"Get NHL standings for a season with points, wins, losses, overtime losses, goals for and against, home and road record and streak. Use for \"Show the NHL standings\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"season":{"anyOf":[{"maximum":2100,"minimum":1900,"type":"integer"},{"type":"null"}],"default":null,"description":"Season year, for example 2025.","title":"Season"},"conference":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Conference name filter.","title":"Conference"},"division":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Division name filter.","title":"Division"}},"title":"get_standingsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_box_scores":{"post":{"operationId":"list_box_scores","summary":"List per-game player box score lines (goals, assists, shots, hits, time on ice, saves) filtered by player, team, date, s","description":"List per-game player box score lines (goals, assists, shots, hits, time on ice, saves) filtered by player, team, date, season or game. Use for \"How many points did player 1 score in January 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"player_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only lines of this player id.","title":"Player Id"},"team_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only lines of this team id.","title":"Team Id"},"date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only games on this date, YYYY-MM-DD.","title":"Date"},"season":{"anyOf":[{"maximum":2100,"minimum":1900,"type":"integer"},{"type":"null"}],"default":null,"description":"Season year.","title":"Season"},"game_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only lines of this game id.","title":"Game Id"},"cursor":{"anyOf":[{"maximum":100000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: the next_cursor value from the previous answer's meta.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Per Page"}},"title":"list_box_scoresArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_player_leaders":{"post":{"operationId":"get_player_leaders","summary":"Get NHL player leaders for one statistic in a season, ranked. Use for \"Who led the NHL in goals in 2025\".","description":"Get NHL player leaders for one statistic in a season, ranked. Use for \"Who led the NHL in goals in 2025\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"description":"Statistic to rank by.","enum":["goals","power_play_points","game_winning_goals","plus_minus","even_strength_points","shots_against","goals_against_average","games_played","goals_against","shots","games_started","short_handed_goals","short_handed_points","faceoff_win_pct","assists","save_pct","power_play_goals","time_on_ice_per_game","wins","ot_losses","overtime_goals","penalty_minutes","saves","points","even_strength_goals","shutouts","shooting_pct","time_on_ice","points_per_game","losses"],"title":"Type","type":"string"},"season":{"description":"Season year, for example 2025.","maximum":2100,"minimum":1900,"title":"Season","type":"integer"},"postseason":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True for playoff statistics, false or omitted for the regular season.","title":"Postseason"}},"required":["type","season"],"title":"get_player_leadersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_team_leaders":{"post":{"operationId":"get_team_leaders","summary":"Get NHL team leaders for one statistic in a season, ranked. Use for \"Which team scored the most goals per game in 2025\".","description":"Get NHL team leaders for one statistic in a season, ranked. Use for \"Which team scored the most goals per game in 2025\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"description":"Statistic to rank by.","enum":["faceoff_win_percentage","shots_for_per_game","penalty_kill_percentage","goals_against_per_game","games_played","goals_for_per_game","goals_against","points_pct","points","power_play_percentage","shots_against_per_game","goals_for","wins","goal_differential","ot_losses","losses"],"title":"Type","type":"string"},"season":{"description":"Season year, for example 2025.","maximum":2100,"minimum":1900,"title":"Season","type":"integer"},"postseason":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True for playoff statistics, false or omitted for the regular season.","title":"Postseason"}},"required":["type","season"],"title":"get_team_leadersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}