{"openapi":"3.1.0","info":{"title":"RetroAchievements (BYOK) API","version":"0.1.0","description":"RetroAchievements (BYOK) lets an AI assistant read your own RetroAchievements data through the RetroAchievements API with a key you supply (RetroAchievements web API key). Read-only: 10 tools (get_console_ids, list_system_games, get_game, get_game_extended, get_game_masters_and_high_scores, get_user_profile, get_user_points, get_user_completion_progress, get_user_recently_played_games,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-retroachievements.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-retroachievements/docs"},"termsOfService":"https://connectorbay.com/byok-retroachievements/terms"},"servers":[{"url":"https://byok-retroachievements.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-retroachievements/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_console_ids":{"post":{"operationId":"get_console_ids","summary":"List every system (console) on RetroAchievements with its id, name and whether it is active and a game system. Use for \"","description":"List every system (console) on RetroAchievements with its id, name and whether it is active and a game system. Use for \"What is the RetroAchievements system id for Mega Drive\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"active_only":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"1 to return only active systems, 0 for all.","title":"Active Only"},"game_systems_only":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"1 to return only gaming systems (leaves out hubs and events), 0 for all.","title":"Game Systems Only"}},"title":"get_console_idsArguments","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_system_games":{"post":{"operationId":"list_system_games","summary":"List the games of one system with achievement count, points and last modified date; large systems are long, so page with","description":"List the games of one system with achievement count, points and last modified date; large systems are long, so page with count and offset. Use for \"Which Mega Drive games have achievements on RetroAchievements\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"system_id":{"description":"System id from get_console_ids, for example 1 for Mega Drive.","minimum":1,"title":"System Id","type":"integer"},"with_achievements_only":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":1,"description":"1 to return only games that have achievements, 0 for all games.","title":"With Achievements Only"},"count":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (default 50, maximum 500).","title":"Count"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip, for paging.","title":"Offset"}},"required":["system_id"],"title":"list_system_gamesArguments","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_game":{"post":{"operationId":"get_game","summary":"Get basic metadata of one game: title, system, publisher, developer, genre and release date. Use for \"Who developed and ","description":"Get basic metadata of one game: title, system, publisher, developer, genre and release date. Use for \"Who developed and published game 1 on RetroAchievements\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"game_id":{"description":"RetroAchievements numeric game id, for example 1 (Sonic the Hedgehog). Find ids with list_system_games.","minimum":1,"title":"Game Id","type":"integer"}},"required":["game_id"],"title":"get_gameArguments","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_game_extended":{"post":{"operationId":"get_game_extended","summary":"Get extended details of one game: player counts, number of achievements, last update, parent game and guide link (the ac","description":"Get extended details of one game: player counts, number of achievements, last update, parent game and guide link (the achievement list itself is left out). Use for \"How many players and achievements does RetroAchievements game 1 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"game_id":{"description":"RetroAchievements numeric game id, for example 1 (Sonic the Hedgehog). Find ids with list_system_games.","minimum":1,"title":"Game Id","type":"integer"}},"required":["game_id"],"title":"get_game_extendedArguments","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_game_masters_and_high_scores":{"post":{"operationId":"get_game_masters_and_high_scores","summary":"List players who completed a game's set (latest masters) or the highest scorers on it, with achievements and score. Use ","description":"List players who completed a game's set (latest masters) or the highest scorers on it, with achievements and score. Use for \"Who recently mastered RetroAchievements game 14402\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"game_id":{"description":"RetroAchievements numeric game id.","minimum":1,"title":"Game Id","type":"integer"},"latest_masters":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":1,"description":"1 for the latest masters (most recent first), 0 for the non-master high scores.","title":"Latest Masters"}},"required":["game_id"],"title":"get_game_masters_and_high_scoresArguments","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_user_profile":{"post":{"operationId":"get_user_profile","summary":"Get a player's public profile summary: member since date, points, motto and last game played. Use for \"When did RetroAch","description":"Get a player's public profile summary: member since date, points, motto and last game played. Use for \"When did RetroAchievements user MaxMilyin join and how many points do they have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"username":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"RetroAchievements username or ULID. Leave out to use the key owner's own account.","title":"Username"}},"title":"get_user_profileArguments","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_user_points":{"post":{"operationId":"get_user_points","summary":"Get a player's hardcore and softcore point totals. Use for \"How many hardcore points does RetroAchievements user Hexadig","description":"Get a player's hardcore and softcore point totals. Use for \"How many hardcore points does RetroAchievements user Hexadigital have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"username":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"RetroAchievements username or ULID. Leave out to use the key owner's own account.","title":"Username"}},"title":"get_user_pointsArguments","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_user_completion_progress":{"post":{"operationId":"get_user_completion_progress","summary":"List games a player has progress in, with achievements awarded and the highest award earned for each, paged. Use for \"Wh","description":"List games a player has progress in, with achievements awarded and the highest award earned for each, paged. Use for \"Which games has RetroAchievements user MaxMilyin beaten or mastered\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"username":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"RetroAchievements username or ULID. Leave out to use the key owner's own account.","title":"Username"},"count":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records to return (default 100, maximum 500).","title":"Count"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip, for paging.","title":"Offset"}},"title":"get_user_completion_progressArguments","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_user_recently_played_games":{"post":{"operationId":"get_user_recently_played_games","summary":"List the games a player played most recently with achievements earned and score for each. Use for \"What has RetroAchieve","description":"List the games a player played most recently with achievements earned and score for each. Use for \"What has RetroAchievements user MaxMilyin been playing lately\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"username":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"RetroAchievements username or ULID. Leave out to use the key owner's own account.","title":"Username"},"count":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records to return (default 10, maximum 50).","title":"Count"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip, for paging.","title":"Offset"}},"title":"get_user_recently_played_gamesArguments","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_user_recent_achievements":{"post":{"operationId":"get_user_recent_achievements","summary":"List achievements a player unlocked in the last N minutes with game, points and mode. Use for \"What did RetroAchievement","description":"List achievements a player unlocked in the last N minutes with game, points and mode. Use for \"What did RetroAchievements user Scott unlock in the last hour\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"username":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"RetroAchievements username or ULID. Leave out to use the key owner's own account.","title":"Username"},"minutes":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":60,"description":"How many minutes to look back (default 60).","title":"Minutes"}},"title":"get_user_recent_achievementsArguments","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}}}}