{"openapi":"3.1.0","info":{"title":"Sportmonks (BYOK) API","version":"0.1.0","description":"Sportmonks (BYOK) lets an AI assistant read your own Sportmonks data through the Sportmonks API with a key you supply (Sportmonks API token). Read-only: 12 tools (list_inplay_livescores, list_fixtures_by_date, get_fixture, list_head_to_head, search_fixtures, list_team_fixtures_between, list_leagues, list_seasons, get_standings_by_season, get_topscorers_by_season, search_teams, search_players)....\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-sportmonks.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-sportmonks/docs"},"termsOfService":"https://connectorbay.com/byok-sportmonks/terms"},"servers":[{"url":"https://byok-sportmonks.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-sportmonks/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_inplay_livescores":{"post":{"operationId":"list_inplay_livescores","summary":"List the football matches in play right now (within your plan's leagues) with teams in the name, start time and state. A","description":"List the football matches in play right now (within your plan's leagues) with teams in the name, start time and state. Add include=scores;participants for scores. Use for \"Which football matches are live right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to attach, separated by semicolons, for example 'participants;scores;league'. Which includes exist depends on the plan; see the docs.","title":"Include"}},"title":"list_inplay_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/list_fixtures_by_date":{"post":{"operationId":"list_fixtures_by_date","summary":"List the football fixtures on one calendar date (YYYY-MM-DD) within your plan's leagues; up to 50 per page. Use for \"Wha","description":"List the football fixtures on one calendar date (YYYY-MM-DD) within your plan's leagues; up to 50 per page. Use for \"What football matches are on 2026-10-17\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date":{"description":"Date as YYYY-MM-DD.","maxLength":10,"title":"Date","type":"string"},"include":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to attach, separated by semicolons, for example 'participants;scores;league'. Which includes exist depends on the plan; see the docs.","title":"Include"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by start time: asc (default) or desc.","title":"Order"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 50, default 25).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; use pagination.has_more to see if more exist.","title":"Page"}},"required":["date"],"title":"list_fixtures_by_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_fixture":{"post":{"operationId":"get_fixture","summary":"Get one football fixture by its ID: teams, start time, state and result text; add includes for scores, events, lineups a","description":"Get one football fixture by its ID: teams, start time, state and result text; add includes for scores, events, lineups and statistics. Use for \"Give me the details of fixture 19146700 with scores and events\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fixture_id":{"description":"Sportmonks fixture ID.","title":"Fixture Id","type":"integer"},"include":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to attach, separated by semicolons, for example 'participants;scores;league'. Which includes exist depends on the plan; see the docs.","title":"Include"}},"required":["fixture_id"],"title":"get_fixtureArguments","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_head_to_head":{"post":{"operationId":"list_head_to_head","summary":"List past fixtures between two teams (by team IDs), newest data first as the API returns them. Use for \"What are the pre","description":"List past fixtures between two teams (by team IDs), newest data first as the API returns them. Use for \"What are the previous matches between team 53 and team 62\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_id_1":{"description":"ID of the first team.","title":"Team Id 1","type":"integer"},"team_id_2":{"description":"ID of the second team.","title":"Team Id 2","type":"integer"},"include":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to attach, separated by semicolons, for example 'participants;scores;league'. Which includes exist depends on the plan; see the docs.","title":"Include"}},"required":["team_id_1","team_id_2"],"title":"list_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/search_fixtures":{"post":{"operationId":"search_fixtures","summary":"Search fixtures by team or match name text, for example 'Celtic'. Use for \"Find fixtures with Celtic\".","description":"Search fixtures by team or match name text, for example 'Celtic'. Use for \"Find fixtures with Celtic\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_query":{"description":"Text to search in fixture names (a team name works).","maxLength":100,"title":"Search Query","type":"string"},"include":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to attach, separated by semicolons, for example 'participants;scores;league'. Which includes exist depends on the plan; see the docs.","title":"Include"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc (default) or desc by start time.","title":"Order"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 50, default 25).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; use pagination.has_more to see if more exist.","title":"Page"}},"required":["search_query"],"title":"search_fixturesArguments","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_team_fixtures_between":{"post":{"operationId":"list_team_fixtures_between","summary":"List one team's fixtures between two dates (YYYY-MM-DD). Use for \"What are Rangers' fixtures between 2026-11-01 and 2026","description":"List one team's fixtures between two dates (YYYY-MM-DD). Use for \"What are Rangers' fixtures between 2026-11-01 and 2026-11-30\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"First date, YYYY-MM-DD.","maxLength":10,"title":"Start Date","type":"string"},"end_date":{"description":"Last date, YYYY-MM-DD.","maxLength":10,"title":"End Date","type":"string"},"team_id":{"description":"Sportmonks team ID.","title":"Team Id","type":"integer"},"include":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to attach, separated by semicolons, for example 'participants;scores;league'. Which includes exist depends on the plan; see the docs.","title":"Include"}},"required":["start_date","end_date","team_id"],"title":"list_team_fixtures_betweenArguments","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 in your plan with country, type, short code and last played time. Use for \"Which leagues does my Sportm","description":"List the leagues in your plan with country, type, short code and last played time. Use for \"Which leagues does my Sportmonks plan include\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to attach, separated by semicolons, for example 'participants;scores;league'. Which includes exist depends on the plan; see the docs.","title":"Include"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by ID: asc (default) or desc.","title":"Order"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 50, default 25).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; use pagination.has_more to see if more exist.","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/list_seasons":{"post":{"operationId":"list_seasons","summary":"List seasons with their league, name, start and end dates and whether each is the current or finished one. Use for \"What","description":"List seasons with their league, name, start and end dates and whether each is the current or finished one. Use for \"What is the current season ID of league 501\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to attach, separated by semicolons, for example 'participants;scores;league'. Which includes exist depends on the plan; see the docs.","title":"Include"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by ID: asc (default) or desc.","title":"Order"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 50, default 25).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; use pagination.has_more to see if more exist.","title":"Page"}},"title":"list_seasonsArguments","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_by_season":{"post":{"operationId":"get_standings_by_season","summary":"Get the full league table of a season: each team's position, points and last result trend. Use for \"Show the league tabl","description":"Get the full league table of a season: each team's position, points and last result trend. Use for \"Show the league table for season 19735\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"season_id":{"description":"Sportmonks season ID.","title":"Season Id","type":"integer"},"include":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to attach, separated by semicolons, for example 'participants;scores;league'. Which includes exist depends on the plan; see the docs.","title":"Include"}},"required":["season_id"],"title":"get_standings_by_seasonArguments","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_topscorers_by_season":{"post":{"operationId":"get_topscorers_by_season","summary":"List a season's top scorers (player ID, rank, total); add include=player;participant for names and clubs. Use for \"Who a","description":"List a season's top scorers (player ID, rank, total); add include=player;participant for names and clubs. Use for \"Who are the top scorers in season 19735\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"season_id":{"description":"Sportmonks season ID.","title":"Season Id","type":"integer"},"include":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to attach, separated by semicolons, for example 'participants;scores;league'. Which includes exist depends on the plan; see the docs.","title":"Include"}},"required":["season_id"],"title":"get_topscorers_by_seasonArguments","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/search_teams":{"post":{"operationId":"search_teams","summary":"Search teams by name, returning ID, country, short code and founding year. Use for \"Find the team ID of Rangers\".","description":"Search teams by name, returning ID, country, short code and founding year. Use for \"Find the team ID of Rangers\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_query":{"description":"Text to search in team names.","maxLength":100,"title":"Search Query","type":"string"},"include":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to attach, separated by semicolons, for example 'participants;scores;league'. Which includes exist depends on the plan; see the docs.","title":"Include"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 50, default 25).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; use pagination.has_more to see if more exist.","title":"Page"}},"required":["search_query"],"title":"search_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/search_players":{"post":{"operationId":"search_players","summary":"Search players by name, returning ID, position, nationality, height, weight and birth date. Use for \"Find the player Jam","description":"Search players by name, returning ID, position, nationality, height, weight and birth date. Use for \"Find the player James Tavernier\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_query":{"description":"Text to search in player names.","maxLength":100,"title":"Search Query","type":"string"},"include":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to attach, separated by semicolons, for example 'participants;scores;league'. Which includes exist depends on the plan; see the docs.","title":"Include"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 50, default 25).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; use pagination.has_more to see if more exist.","title":"Page"}},"required":["search_query"],"title":"search_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}}}}