{"openapi":"3.1.0","info":{"title":"BALLDONTLIE (BYOK) API","version":"0.1.0","description":"BALLDONTLIE (BYOK) lets an AI assistant read your own BALLDONTLIE data through the BALLDONTLIE API with a key you supply (BALLDONTLIE API key). Read-only: 11 tools (list_teams, get_team, list_players, get_player, list_games, get_game, list_player_game_stats, get_season_averages, get_standings, get_stat_leaders, list_player_injuries). The BYOK key travels with each request, is used for that one...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-balldontlie.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-balldontlie/docs"},"termsOfService":"https://connectorbay.com/byok-balldontlie/terms"},"servers":[{"url":"https://byok-balldontlie.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-balldontlie/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 NBA teams with city, conference and division, optionally filtered by conference or division. Use for \"Which NBA tea","description":"List NBA teams with city, conference and division, optionally filtered by conference or division. Use for \"Which NBA teams are in the Western Conference\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"conference":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Conference name: East or West.","title":"Conference"},"division":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Division name, for example Atlantic or Pacific.","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 NBA team by its numeric id. Use for \"Show NBA team 14\".","description":"Get one NBA team by its numeric id. Use for \"Show NBA team 14\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BALLDONTLIE team id, for example 14.","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/list_players":{"post":{"operationId":"list_players","summary":"List or search NBA players by name or team, 100 per page at most, with position, size, college and draft year. Use for \"","description":"List or search NBA players by name or team, 100 per page at most, with position, size, college and draft year. Use for \"Find the NBA player named LeBron James\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Part of a player name to search for.","title":"Search"},"first_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Exact first name filter.","title":"First Name"},"last_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Exact last name filter.","title":"Last 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":{"post":{"operationId":"get_player","summary":"Get one NBA player by id with position, size, college, draft data and current team. Use for \"Show NBA player 237\".","description":"Get one NBA player by id with position, size, college, draft data and current team. Use for \"Show NBA player 237\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BALLDONTLIE player id, for example 237.","minimum":1,"title":"Id","type":"integer"}},"required":["id"],"title":"get_playerArguments","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 NBA games filtered by date, season, team or date range with status, period and scores. Use for \"What NBA games were","description":"List NBA games filtered by date, season, team or date range with status, period and scores. Use for \"What NBA games were played on 2025-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"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only games after this date, YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only games before this date, YYYY-MM-DD.","title":"End Date"},"season":{"anyOf":[{"maximum":2100,"minimum":1946,"type":"integer"},{"type":"null"}],"default":null,"description":"Season year such as 2024 for 2024-25.","title":"Season"},"team_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only games of this team id.","title":"Team Id"},"season_type":{"anyOf":[{"enum":["preseason","regular","ist","playin","playoffs"],"type":"string"},{"type":"null"}],"default":null,"description":"Game type: preseason, regular, ist, playin or playoffs.","title":"Season Type"},"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_game":{"post":{"operationId":"get_game","summary":"Get one NBA game by id with status, period, clock and both teams' scores. Use for \"Show the details of NBA game 15907925","description":"Get one NBA game by id with status, period, clock and both teams' scores. Use for \"Show the details of NBA game 15907925\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BALLDONTLIE game id.","minimum":1,"title":"Id","type":"integer"}},"required":["id"],"title":"get_gameArguments","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_player_game_stats":{"post":{"operationId":"list_player_game_stats","summary":"List per-game box score lines (minutes, points, rebounds, assists, shooting) filtered by player, game, date or season. U","description":"List per-game box score lines (minutes, points, rebounds, assists, shooting) filtered by player, game, date or season. Use for \"How many points did player 237 score in his games in January 2025\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"player_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only stat lines of this player id.","title":"Player Id"},"game_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only stat lines of this game id.","title":"Game Id"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only games after this date, YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only games before this date, YYYY-MM-DD.","title":"End Date"},"season":{"anyOf":[{"maximum":2100,"minimum":1946,"type":"integer"},{"type":"null"}],"default":null,"description":"Season year such as 2024.","title":"Season"},"season_type":{"anyOf":[{"enum":["preseason","regular","ist","playin","playoffs"],"type":"string"},{"type":"null"}],"default":null,"description":"Game type: preseason, regular, ist, playin or playoffs.","title":"Season Type"},"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_player_game_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/get_season_averages":{"post":{"operationId":"get_season_averages","summary":"Get a player's season averages (games played, points, rebounds, assists, shooting percentages) for one season. Use for \"","description":"Get a player's season averages (games played, points, rebounds, assists, shooting percentages) for one season. Use for \"What were player 237's season averages in 2024\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"season":{"description":"Season year such as 2024 for 2024-25.","maximum":2100,"minimum":1946,"title":"Season","type":"integer"},"player_id":{"description":"BALLDONTLIE player id.","minimum":1,"title":"Player Id","type":"integer"}},"required":["season","player_id"],"title":"get_season_averagesArguments","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 NBA team standings for a season with wins, losses, conference and division ranks. Use for \"Show the NBA standings fo","description":"Get NBA team standings for a season with wins, losses, conference and division ranks. Use for \"Show the NBA standings for the 2024 season\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"season":{"description":"Season year such as 2024 for 2024-25.","maximum":2100,"minimum":1946,"title":"Season","type":"integer"}},"required":["season"],"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/get_stat_leaders":{"post":{"operationId":"get_stat_leaders","summary":"Get the NBA leaders for one statistic in a season, ranked, with value and games played. Use for \"Who led the NBA in assi","description":"Get the NBA leaders for one statistic in a season, ranked, with value and games played. Use for \"Who led the NBA in assists in 2024\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"stat_type":{"description":"Statistic: ast, blk, dreb, eff, fg3a, fg3m, fg3_pct, fga, fgm, fg_pct, fta, ftm, ft_pct, min, oreb, pts, reb, stl or tov.","enum":["ast","blk","dreb","eff","fg3a","fg3m","fg3_pct","fga","fgm","fg_pct","fta","ftm","ft_pct","min","oreb","pts","reb","stl","tov"],"title":"Stat Type","type":"string"},"season":{"description":"Season year such as 2024 for 2024-25.","maximum":2100,"minimum":1946,"title":"Season","type":"integer"},"season_type":{"anyOf":[{"enum":["regular","playoffs"],"type":"string"},{"type":"null"}],"default":"regular","description":"regular or playoffs.","title":"Season Type"}},"required":["stat_type","season"],"title":"get_stat_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/list_player_injuries":{"post":{"operationId":"list_player_injuries","summary":"List current NBA player injuries with status, return date and description, optionally for one team or player. Use for \"W","description":"List current NBA player injuries with status, return date and description, optionally for one team or player. Use for \"Which NBA players are injured right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only injuries of this team id.","title":"Team Id"},"player_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only injuries of this player id.","title":"Player 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_player_injuriesArguments","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}}}}