{"openapi":"3.1.0","info":{"title":"Ballchasing (BYOK) API","version":"0.1.0","description":"Ballchasing (BYOK) lets an AI assistant read your own Ballchasing data through the Ballchasing API with a key you supply (ballchasing.com API token). Read-only: 6 tools (get_api_status, list_replays, get_replay, list_groups, get_group, list_maps). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to ballchasing.com....\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-ballchasing.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-ballchasing/docs"},"termsOfService":"https://connectorbay.com/byok-ballchasing/terms"},"servers":[{"url":"https://byok-ballchasing.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-ballchasing/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/get_api_status":{"post":{"operationId":"get_api_status","summary":"Check that the token works and show the account it belongs to, its patron type and upload quota. Use for \"Is my ballchas","description":"Check that the token works and show the account it belongs to, its patron type and upload quota. Use for \"Is my ballchasing token valid and what is my quota\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_api_statusArguments","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_replays":{"post":{"operationId":"list_replays","summary":"List and filter replays by player, playlist, map, season, rank range, result, uploader, group or date, newest uploads fi","description":"List and filter replays by player, playlist, map, season, rank range, result, uploader, group or date, newest uploads first by default. Use for \"Show my last 10 ranked doubles replays on ballchasing\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by replay title text.","title":"Title"},"player_name":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only replays with a player of this name.","title":"Player Name"},"player_id":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only replays with this player platform ID as platform:id, for example 'steam:76561198141161044'.","title":"Player Id"},"playlist":{"anyOf":[{"enum":["unranked-duels","unranked-doubles","unranked-standard","unranked-chaos","private","season","offline","ranked-duels","ranked-doubles","ranked-solo-standard","ranked-standard","snowday","rocketlabs","hoops","rumble","tournament","dropshot","ranked-hoops","ranked-rumble","ranked-dropshot","ranked-snowday","dropshot-rumble","heatseeker"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this playlist.","title":"Playlist"},"season":{"anyOf":[{"maxLength":6,"type":"string"},{"type":"null"}],"default":null,"description":"Season number 1 to 14 for old seasons, or f1, f2 and so on for free-to-play seasons.","title":"Season"},"match_result":{"anyOf":[{"enum":["win","loss"],"type":"string"},{"type":"null"}],"default":null,"description":"win or loss, from the point of view of the matched player.","title":"Match Result"},"min_rank":{"anyOf":[{"enum":["unranked","bronze-1","bronze-2","bronze-3","silver-1","silver-2","silver-3","gold-1","gold-2","gold-3","platinum-1","platinum-2","platinum-3","diamond-1","diamond-2","diamond-3","champion-1","champion-2","champion-3","grand-champion"],"type":"string"},{"type":"null"}],"default":null,"description":"Minimum player rank.","title":"Min Rank"},"max_rank":{"anyOf":[{"enum":["unranked","bronze-1","bronze-2","bronze-3","silver-1","silver-2","silver-3","gold-1","gold-2","gold-3","platinum-1","platinum-2","platinum-3","diamond-1","diamond-2","diamond-3","champion-1","champion-2","champion-3","grand-champion"],"type":"string"},{"type":"null"}],"default":null,"description":"Maximum player rank.","title":"Max Rank"},"pro":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to only include replays with at least one pro player.","title":"Pro"},"uploader":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Uploader's SteamID64, or 'me' for the token's owner.","title":"Uploader"},"group":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only replays directly in this group ID.","title":"Group"},"map":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only this map code (see list_maps).","title":"Map"},"created_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Uploaded before this time (RFC 3339, e.g. 2026-01-02T15:00:05+01:00).","title":"Created Before"},"created_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Uploaded after this time (RFC 3339).","title":"Created After"},"replay_date_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Played before this time (RFC 3339).","title":"Replay Date Before"},"replay_date_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Played after this time (RFC 3339).","title":"Replay Date After"},"count":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many replays (1 to 200, default 20 here).","title":"Count"},"sort_by":{"anyOf":[{"enum":["replay-date","upload-date"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by replay-date or upload-date (default).","title":"Sort By"},"sort_dir":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc (default).","title":"Sort Dir"}},"title":"list_replaysArguments","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_replay":{"post":{"operationId":"get_replay","summary":"Get one replay's full details and per-player and per-team stats: score, shots, saves, boost, movement, positioning and d","description":"Get one replay's full details and per-player and per-team stats: score, shots, saves, boost, movement, positioning and demos. Use for \"Show the stats of replay 56889c3e-c420-45db-92fd-47ce2a3604b0\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Replay ID (a UUID from list_replays).","maxLength":64,"title":"Id","type":"string"}},"required":["id"],"title":"get_replayArguments","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_groups":{"post":{"operationId":"list_groups","summary":"List replay groups (series, tournaments) filtered by name, creator, parent group or date. Use for \"Which replay groups m","description":"List replay groups (series, tournaments) filtered by name, creator, parent group or date. Use for \"Which replay groups mention RLCS\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by group name text.","title":"Name"},"creator":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Creator's SteamID64, or 'me'.","title":"Creator"},"group":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only children of this group ID.","title":"Group"},"created_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Created before this time (RFC 3339).","title":"Created Before"},"created_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Created after this time (RFC 3339).","title":"Created After"},"count":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many groups (1 to 200, default 20 here).","title":"Count"},"sort_by":{"anyOf":[{"enum":["created","name"],"type":"string"},{"type":"null"}],"default":null,"description":"created (default) or name.","title":"Sort By"},"sort_dir":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc (default).","title":"Sort Dir"}},"title":"list_groupsArguments","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_group":{"post":{"operationId":"get_group","summary":"Get one replay group with its players and teams and their cumulative and per-game average stats. Use for \"Give me the pl","description":"Get one replay group with its players and teams and their cumulative and per-game average stats. Use for \"Give me the player stats for group rlcs-s6-final-series-6r6rq5s1zk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Group ID from list_groups.","maxLength":100,"title":"Id","type":"string"}},"required":["id"],"title":"get_groupArguments","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_maps":{"post":{"operationId":"list_maps","summary":"List Rocket League map codes with their stadium names, for use in the map filter. Use for \"What is the ballchasing map c","description":"List Rocket League map codes with their stadium names, for use in the map filter. Use for \"What is the ballchasing map code for Mannfield\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_mapsArguments","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}}}}