{"openapi":"3.1.0","info":{"title":"APIfootball (BYOK) API","version":"0.1.0","description":"APIfootball (BYOK) lets an AI assistant read your own APIfootball data through the APIfootball API with a key you supply (APIfootball API key). Read-only: 9 tools (list_countries, list_leagues, get_teams, find_players, get_standings, list_matches, get_head_to_head, get_top_scorers, get_predictions). The BYOK key travels with each request, is used for that one call only and is never stored, logged...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-apifootball.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-apifootball/docs"},"termsOfService":"https://connectorbay.com/byok-apifootball/terms"},"servers":[{"url":"https://byok-apifootball.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-apifootball/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_countries":{"post":{"operationId":"list_countries","summary":"List the countries with football data included in your subscription plan, with their ids (used as country_id elsewhere).","description":"List the countries with football data included in your subscription plan, with their ids (used as country_id elsewhere). Use for \"Which countries does my APIfootball plan cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"action":{"anyOf":[{"const":"get_countries","type":"string"},{"type":"null"}],"default":"get_countries","description":"Fixed method name for this call; always get_countries.","title":"Action"}},"title":"list_countriesArguments","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_leagues":{"post":{"operationId":"list_leagues","summary":"List the competitions in your plan, optionally for one country, with league id, name and season. Use for \"Which football","description":"List the competitions in your plan, optionally for one country, with league id, name and season. Use for \"Which football leagues exist in Spain\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"action":{"anyOf":[{"const":"get_leagues","type":"string"},{"type":"null"}],"default":"get_leagues","description":"Fixed method name for this call; always get_leagues.","title":"Action"},"country_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only competitions of this country id (from list_countries).","title":"Country Id"}},"title":"list_leaguesArguments","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_teams":{"post":{"operationId":"get_teams","summary":"Get teams of a league, or one team by id: name, country, founding year and home venue. Give league_id or team_id (one is","description":"Get teams of a league, or one team by id: name, country, founding year and home venue. Give league_id or team_id (one is required). Use for \"Which teams play in La Liga (league 302)\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"action":{"anyOf":[{"const":"get_teams","type":"string"},{"type":"null"}],"default":"get_teams","description":"Fixed method name for this call; always get_teams.","title":"Action"},"league_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"League id (from list_leagues). Required when team_id is not given.","title":"League Id"},"team_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Team id. Required when league_id is not given.","title":"Team Id"}},"title":"get_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/find_players":{"post":{"operationId":"find_players","summary":"Find players by name or id and return season statistics: club, position, age, appearances, goals and assists. Give playe","description":"Find players by name or id and return season statistics: club, position, age, appearances, goals and assists. Give player_name or player_id (one is required). Use for \"Show season stats for the player Benzema\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"action":{"anyOf":[{"const":"get_players","type":"string"},{"type":"null"}],"default":"get_players","description":"Fixed method name for this call; always get_players.","title":"Action"},"player_name":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Player name or part of it, for example 'Benzema'. Required when player_id is not given.","title":"Player Name"},"player_id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Player id. Required when player_name is not given.","title":"Player Id"}},"title":"find_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_standings":{"post":{"operationId":"get_standings","summary":"Get the league table of a competition: position, played, won, drawn, lost, goals for and against and points (overall, ho","description":"Get the league table of a competition: position, played, won, drawn, lost, goals for and against and points (overall, home and away exist in the full answer). Use for \"What is the current Premier League table (league 152)\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"league_id":{"description":"League id from list_leagues.","maxLength":10,"title":"League Id","type":"string"},"action":{"anyOf":[{"const":"get_standings","type":"string"},{"type":"null"}],"default":"get_standings","description":"Fixed method name for this call; always get_standings.","title":"Action"}},"required":["league_id"],"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_matches":{"post":{"operationId":"list_matches","summary":"List fixtures and results between two dates, optionally for one league, country or team, or one match id; set live_only ","description":"List fixtures and results between two dates, optionally for one league, country or team, or one match id; set live_only for matches in play. Use for \"What Premier League matches are played between 2026-03-01 and 2026-03-07\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date_from":{"description":"Start date, YYYY-MM-DD.","maxLength":10,"title":"Date From","type":"string"},"date_to":{"description":"End date, YYYY-MM-DD.","maxLength":10,"title":"Date To","type":"string"},"action":{"anyOf":[{"const":"get_events","type":"string"},{"type":"null"}],"default":"get_events","description":"Fixed method name for this call; always get_events.","title":"Action"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Time zone for match times in TZ format such as 'America/New_York' (provider default is Europe/Berlin).","title":"Timezone"},"league_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only this league id.","title":"League Id"},"country_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only this country id.","title":"Country Id"},"team_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only matches of this team id.","title":"Team Id"},"match_id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only this match id.","title":"Match Id"},"live_only":{"anyOf":[{"const":"1","type":"string"},{"type":"null"}],"default":null,"description":"Set to 1 to return only live matches.","title":"Live Only"}},"required":["date_from","date_to"],"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_head_to_head":{"post":{"operationId":"get_head_to_head","summary":"Get the previous meetings of two teams (by ids) with dates and scores. Use for \"How did team 7275 and team 151 do in the","description":"Get the previous meetings of two teams (by ids) with dates and scores. Use for \"How did team 7275 and team 151 do in their last games against each other\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"first_team_id":{"description":"Id of the first team.","maxLength":10,"title":"First Team Id","type":"string"},"second_team_id":{"description":"Id of the second team.","maxLength":10,"title":"Second Team Id","type":"string"},"action":{"anyOf":[{"const":"get_H2H","type":"string"},{"type":"null"}],"default":"get_H2H","description":"Fixed method name for this call; always get_H2H.","title":"Action"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Time zone for match times in TZ format such as 'America/New_York' (provider default is Europe/Berlin).","title":"Timezone"}},"required":["first_team_id","second_team_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}},"/v1/tools/get_top_scorers":{"post":{"operationId":"get_top_scorers","summary":"List the top scorers of a league with rank, player, team, goals, assists and penalty goals. Use for \"Who are the top sco","description":"List the top scorers of a league with rank, player, team, goals, assists and penalty goals. Use for \"Who are the top scorers in La Liga (league 302)\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"league_id":{"description":"League id from list_leagues.","maxLength":10,"title":"League Id","type":"string"},"action":{"anyOf":[{"const":"get_topscorers","type":"string"},{"type":"null"}],"default":"get_topscorers","description":"Fixed method name for this call; always get_topscorers.","title":"Action"}},"required":["league_id"],"title":"get_top_scorersArguments","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_predictions":{"post":{"operationId":"get_predictions","summary":"List calculated match predictions for fixtures between two dates, optionally per league, country or match id. Use for \"W","description":"List calculated match predictions for fixtures between two dates, optionally per league, country or match id. Use for \"What are the predicted outcomes for matches on 2026-03-05\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date_from":{"description":"Start date, YYYY-MM-DD.","maxLength":10,"title":"Date From","type":"string"},"date_to":{"description":"End date, YYYY-MM-DD.","maxLength":10,"title":"Date To","type":"string"},"action":{"anyOf":[{"const":"get_predictions","type":"string"},{"type":"null"}],"default":"get_predictions","description":"Fixed method name for this call; always get_predictions.","title":"Action"},"league_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only this league id.","title":"League Id"},"country_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only this country id.","title":"Country Id"},"match_id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only this match id.","title":"Match Id"}},"required":["date_from","date_to"],"title":"get_predictionsArguments","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}}}}