{"openapi":"3.1.0","info":{"title":"BALLDONTLIE ATP (BYOK) API","version":"0.1.0","description":"BALLDONTLIE ATP (BYOK) lets an AI assistant read your own BALLDONTLIE ATP data through the BALLDONTLIE ATP API with a key you supply (BALLDONTLIE API key). Read-only: 11 tools (list_players, get_player, list_tournaments, get_tournament, get_rankings, get_atp_race, list_matches, get_match, list_match_stats, list_player_career_stats, get_head_to_head). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-balldontlie-atp.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-balldontlie-atp/docs"},"termsOfService":"https://connectorbay.com/byok-balldontlie-atp/terms"},"servers":[{"url":"https://byok-balldontlie-atp.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-balldontlie-atp/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_players":{"post":{"operationId":"list_players","summary":"List or search ATP tennis players by name or country with age, size, playing hand and the year they turned professional;","description":"List or search ATP tennis players by name or country with age, size, playing hand and the year they turned professional; 100 per page at most. Use for \"Find the tennis player Sinner\".","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"},"country":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Country name filter.","title":"Country"},"country_code":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":null,"description":"Country code filter, for example ITA.","title":"Country Code"},"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 ATP player by id. Use for \"Show ATP player 1\".","description":"Get one ATP player by id. Use for \"Show ATP player 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BALLDONTLIE player id, for example 1.","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_tournaments":{"post":{"operationId":"list_tournaments","summary":"List ATP tournaments filtered by season, surface or category with location, dates, prize money and draw size. Use for \"W","description":"List ATP tournaments filtered by season, surface or category with location, dates, prize money and draw size. Use for \"Which ATP tournaments are played on clay in 2026\".","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 2026.","title":"Season"},"surface":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Court surface, for example Clay, Hard or Grass.","title":"Surface"},"category":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Tournament category, for example Grand Slam.","title":"Category"},"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_tournamentsArguments","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_tournament":{"post":{"operationId":"get_tournament","summary":"Get one ATP tournament by id, optionally for a given season. Use for \"Show ATP tournament 1\".","description":"Get one ATP tournament by id, optionally for a given season. Use for \"Show ATP tournament 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BALLDONTLIE tournament id, for example 1.","minimum":1,"title":"Id","type":"integer"},"season":{"anyOf":[{"maximum":2100,"minimum":1900,"type":"integer"},{"type":"null"}],"default":null,"description":"Season year.","title":"Season"}},"required":["id"],"title":"get_tournamentArguments","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_rankings":{"post":{"operationId":"get_rankings","summary":"Get ATP singles rankings (latest, or for a date) with rank, points and movement. Use for \"Who is ranked first in the ATP","description":"Get ATP singles rankings (latest, or for a date) with rank, points and movement. Use for \"Who is ranked first in the ATP rankings\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Ranking date, YYYY-MM-DD; latest when omitted.","title":"Date"},"player_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only 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":"get_rankingsArguments","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_atp_race":{"post":{"operationId":"get_atp_race","summary":"Get the ATP Race to Turin season standings with rank, points, movement and qualification flag. Use for \"Who is qualified","description":"Get the ATP Race to Turin season standings with rank, points, movement and qualification flag. Use for \"Who is qualified for the ATP Finals race\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Ranking date, YYYY-MM-DD; latest when omitted.","title":"Date"},"player_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only 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":"get_atp_raceArguments","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_matches":{"post":{"operationId":"list_matches","summary":"List ATP matches filtered by tournament, player, season, round or live status with players, winner, score and duration. ","description":"List ATP matches filtered by tournament, player, season, round or live status with players, winner, score and duration. Use for \"What ATP matches are live now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tournament_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only matches of this tournament id.","title":"Tournament Id"},"player_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only matches of this player id.","title":"Player Id"},"season":{"anyOf":[{"maximum":2100,"minimum":1900,"type":"integer"},{"type":"null"}],"default":null,"description":"Season year.","title":"Season"},"round":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Round name, for example Final.","title":"Round"},"is_live":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for matches in progress only.","title":"Is Live"},"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_matchesArguments","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_match":{"post":{"operationId":"get_match","summary":"Get one ATP match by id with players, winner, score, set count and duration. Use for \"Show ATP match 1\".","description":"Get one ATP match by id with players, winner, score, set count and duration. Use for \"Show ATP match 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"BALLDONTLIE match id, for example 1.","minimum":1,"title":"Id","type":"integer"}},"required":["id"],"title":"get_matchArguments","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_match_stats":{"post":{"operationId":"list_match_stats","summary":"List ATP match statistics (aces, double faults, serve and return percentages, break points) per player and set. Use for ","description":"List ATP match statistics (aces, double faults, serve and return percentages, break points) per player and set. Use for \"What were the serve stats of match 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"match_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only rows of this match id.","title":"Match Id"},"player_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only rows of this player id.","title":"Player Id"},"set_number":{"anyOf":[{"maximum":5,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this set number.","title":"Set Number"},"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_match_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_player_career_stats":{"post":{"operationId":"list_player_career_stats","summary":"List ATP players' career totals: titles, prize money, singles wins and losses and year-to-date record. Use for \"How many","description":"List ATP players' career totals: titles, prize money, singles wins and losses and year-to-date record. Use for \"How many titles has player 1 won\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"player_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only 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_career_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_head_to_head":{"post":{"operationId":"get_head_to_head","summary":"Get the head-to-head win record of two ATP players. Use for \"What is the head-to-head between players 1 and 2\".","description":"Get the head-to-head win record of two ATP players. Use for \"What is the head-to-head between players 1 and 2\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"player1_id":{"description":"First player id.","minimum":1,"title":"Player1 Id","type":"integer"},"player2_id":{"description":"Second player id.","minimum":1,"title":"Player2 Id","type":"integer"}},"required":["player1_id","player2_id"],"title":"get_head_to_headArguments","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}}}}