{"openapi":"3.1.0","info":{"title":"SoccersAPI (BYOK) API","version":"0.1.0","description":"SoccersAPI (BYOK) lets an AI assistant read your own SoccersAPI data through the SoccersAPI API with a key you supply (SoccersAPI API key). Read-only: 12 tools (search_football, list_leagues, get_league, get_standings, list_matches_on_date, get_match, get_match_events, get_team_last_and_next, list_livescores, get_team, get_team_squad, get_season_leaders). The BYOK key travels with each request,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-soccersapi.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-soccersapi/docs"},"termsOfService":"https://connectorbay.com/byok-soccersapi/terms"},"servers":[{"url":"https://byok-soccersapi.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-soccersapi/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/search_football":{"post":{"operationId":"search_football","summary":"Search football entities by name: teams, leagues, players, referees or countries. Returns ids to use in the other tools.","description":"Search football entities by name: teams, leagues, players, referees or countries. Returns ids to use in the other tools. Use for \"What is the team id of Barcelona\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Name or part of a name to look for.","maxLength":100,"title":"Q","type":"string"},"operation":{"anyOf":[{"enum":["team","league","player","referee","country"],"type":"string"},{"type":"null"}],"default":"team","description":"Fixed operation selector sent as the t parameter; one of team, league, player, referee, country.","title":"Operation"}},"required":["q"],"title":"search_footballArguments","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 leagues available to the account, optionally for one country, with current season, stage and round ids (100 per","description":"List the leagues available to the account, optionally for one country, with current season, stage and round ids (100 per page). Use for \"Which football leagues are there in Germany\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"operation":{"anyOf":[{"const":"list","type":"string"},{"type":"null"}],"default":"list","description":"Fixed operation selector sent as the t parameter; always list.","title":"Operation"},"country_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only leagues of this country id (from search_football with the country type).","title":"Country Id"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Page number, starting at 1 (lists return up to 100 items per page).","title":"Page"}},"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_league":{"post":{"operationId":"get_league","summary":"Get one league profile with its country, seasons and the ids of the current season, stage and round. Use for \"What is th","description":"Get one league profile with its country, seasons and the ids of the current season, stage and round. Use for \"What is the current season id of league 594\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"League id.","maxLength":20,"title":"Id","type":"string"},"operation":{"anyOf":[{"const":"info","type":"string"},{"type":"null"}],"default":"info","description":"Fixed operation selector sent as the t parameter; always info.","title":"Operation"}},"required":["id"],"title":"get_leagueArguments","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 season: team, played, won, drawn, lost, goals and points overall, home and away (Standard plan","description":"Get the league table of a season: team, played, won, drawn, lost, goals and points overall, home and away (Standard plan datasets). Use for \"Show the standings of season 406\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"season_id":{"description":"Season id from get_league.","maxLength":20,"title":"Season Id","type":"string"},"operation":{"anyOf":[{"enum":["standings","standings_live"],"type":"string"},{"type":"null"}],"default":"standings","description":"Fixed operation selector sent as the t parameter; one of standings, standings_live.","title":"Operation"}},"required":["season_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_on_date":{"post":{"operationId":"list_matches_on_date","summary":"List the matches played on a date, optionally narrowed to a league or country (100 per page). Use for \"Which football ma","description":"List the matches played on a date, optionally narrowed to a league or country (100 per page). Use for \"Which football matches are on 2026-08-30 in league 583\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"d":{"description":"Date as YYYY-MM-DD.","maxLength":10,"title":"D","type":"string"},"operation":{"anyOf":[{"const":"schedule","type":"string"},{"type":"null"}],"default":"schedule","description":"Fixed operation selector sent as the t parameter; always schedule.","title":"Operation"},"league_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this league id.","title":"League Id"},"country_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this country id.","title":"Country Id"},"utc":{"anyOf":[{"maximum":14,"minimum":-12,"type":"number"},{"type":"null"}],"default":null,"description":"UTC offset in hours applied to returned dates and times, for example 2 or 5.5 (default UTC).","title":"Utc"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Page number, starting at 1 (lists return up to 100 items per page).","title":"Page"}},"required":["d"],"title":"list_matches_on_dateArguments","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 match with teams, league, venue, scores, status and clock. Use for \"What was the result of match 2589310\".","description":"Get one match with teams, league, venue, scores, status and clock. Use for \"What was the result of match 2589310\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Match id.","maxLength":20,"title":"Id","type":"string"},"operation":{"anyOf":[{"const":"info","type":"string"},{"type":"null"}],"default":"info","description":"Fixed operation selector sent as the t parameter; always info.","title":"Operation"},"utc":{"anyOf":[{"maximum":14,"minimum":-12,"type":"number"},{"type":"null"}],"default":null,"description":"UTC offset in hours applied to returned dates and times, for example 2 or 5.5 (default UTC).","title":"Utc"}},"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/get_match_events":{"post":{"operationId":"get_match_events","summary":"Get the event timeline of a match: goals, cards, substitutions and corners with minute and player. Use for \"What happene","description":"Get the event timeline of a match: goals, cards, substitutions and corners with minute and player. Use for \"What happened in match 2589310\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Match id.","maxLength":20,"title":"Id","type":"string"},"operation":{"anyOf":[{"const":"match_events","type":"string"},{"type":"null"}],"default":"match_events","description":"Fixed operation selector sent as the t parameter; always match_events.","title":"Operation"}},"required":["id"],"title":"get_match_eventsArguments","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_last_and_next":{"post":{"operationId":"get_team_last_and_next","summary":"Get a team's recent results, matches in play and upcoming matches (data.last, data.current, data.next). Use for \"What ar","description":"Get a team's recent results, matches in play and upcoming matches (data.last, data.current, data.next). Use for \"What are Barcelona's last results and next matches\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_id":{"description":"Team id.","maxLength":20,"title":"Team Id","type":"string"},"operation":{"anyOf":[{"const":"last_next","type":"string"},{"type":"null"}],"default":"last_next","description":"Fixed operation selector sent as the t parameter; always last_next.","title":"Operation"},"utc":{"anyOf":[{"maximum":14,"minimum":-12,"type":"number"},{"type":"null"}],"default":null,"description":"UTC offset in hours applied to returned dates and times, for example 2 or 5.5 (default UTC).","title":"Utc"}},"required":["team_id"],"title":"get_team_last_and_nextArguments","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_livescores":{"post":{"operationId":"list_livescores","summary":"List matches by live state: live now, today, tomorrow, yesterday, not started or ended (100 per page). Use for \"Which fo","description":"List matches by live state: live now, today, tomorrow, yesterday, not started or ended (100 per page). Use for \"Which football matches are live right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"operation":{"anyOf":[{"enum":["live","today","tomorrow","yesterday","notstarted","ended"],"type":"string"},{"type":"null"}],"default":"live","description":"Fixed operation selector sent as the t parameter; one of live, today, tomorrow, yesterday, notstarted, ended.","title":"Operation"},"utc":{"anyOf":[{"maximum":14,"minimum":-12,"type":"number"},{"type":"null"}],"default":null,"description":"UTC offset in hours applied to returned dates and times, for example 2 or 5.5 (default UTC).","title":"Utc"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Page number, starting at 1 (lists return up to 100 items per page).","title":"Page"}},"title":"list_livescoresArguments","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 a team profile: name, country, founding year, coach id, venue id, leagues and current seasons. Use for \"Tell me abou","description":"Get a team profile: name, country, founding year, coach id, venue id, leagues and current seasons. Use for \"Tell me about team 111\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Team id.","maxLength":20,"title":"Id","type":"string"},"operation":{"anyOf":[{"const":"info","type":"string"},{"type":"null"}],"default":"info","description":"Fixed operation selector sent as the t parameter; always info.","title":"Operation"}},"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_squad":{"post":{"operationId":"get_team_squad","summary":"Get a team's squad (current, or of a past season) with shirt number, position and player ids. Use for \"Who is in the squ","description":"Get a team's squad (current, or of a past season) with shirt number, position and player ids. Use for \"Who is in the squad of team 111\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Team id.","maxLength":20,"title":"Id","type":"string"},"operation":{"anyOf":[{"const":"squad","type":"string"},{"type":"null"}],"default":"squad","description":"Fixed operation selector sent as the t parameter; always squad.","title":"Operation"},"season_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Season id for a past squad (default: current).","title":"Season Id"}},"required":["id"],"title":"get_team_squadArguments","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_leaders":{"post":{"operationId":"get_season_leaders","summary":"Rank players of a season by goals, assists or cards. Use for \"Who are the top scorers in season 12516\".","description":"Rank players of a season by goals, assists or cards. Use for \"Who are the top scorers in season 12516\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"season_id":{"description":"Season id.","maxLength":20,"title":"Season Id","type":"string"},"operation":{"anyOf":[{"enum":["topscorers","topassists","topcards"],"type":"string"},{"type":"null"}],"default":"topscorers","description":"Fixed operation selector sent as the t parameter; one of topscorers, topassists, topcards.","title":"Operation"}},"required":["season_id"],"title":"get_season_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}}}}