{"openapi":"3.1.0","info":{"title":"Hypixel (BYOK) API","version":"0.1.0","description":"Hypixel (BYOK) lets an AI assistant read your own Hypixel data through the Hypixel API with a key you supply (API key from the Hypixel developer dashboard). Read-only: 12 tools (get_player, get_recent_games, get_player_status, get_guild, list_skyblock_profiles, list_skyblock_auctions, find_skyblock_auctions, get_skyblock_firesales, get_player_counts, get_punishment_stats, list_active_houses,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-hypixel.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hypixel/docs"},"termsOfService":"https://connectorbay.com/byok-hypixel/terms"},"servers":[{"url":"https://byok-hypixel.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hypixel/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_player":{"post":{"operationId":"get_player","summary":"Get a player's Hypixel profile by UUID: display name, rank, package ranks, first and last login and logout times (millis","description":"Get a player's Hypixel profile by UUID: display name, rank, package ranks, first and last login and logout times (milliseconds). The large per-game stats object is not returned. Use for \"When did this Hypixel player last log in and what rank do they have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"uuid":{"description":"Minecraft account UUID of the player, with or without dashes, for example '069a79f444e94726a5befca90e38aaf5'.","maxLength":40,"title":"Uuid","type":"string"}},"required":["uuid"],"title":"get_playerArguments","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_recent_games":{"post":{"operationId":"get_recent_games","summary":"List a player's recently played games (up to the last 3 days) with game type, mode, map and start and end time. Use for ","description":"List a player's recently played games (up to the last 3 days) with game type, mode, map and start and end time. Use for \"What Hypixel games did this player play recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"uuid":{"description":"Minecraft account UUID of the player, with or without dashes, for example '069a79f444e94726a5befca90e38aaf5'.","maxLength":40,"title":"Uuid","type":"string"}},"required":["uuid"],"title":"get_recent_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_player_status":{"post":{"operationId":"get_player_status","summary":"Show whether a player is online right now and, if so, the game type, mode and map they are in. Use for \"Is this player o","description":"Show whether a player is online right now and, if so, the game type, mode and map they are in. Use for \"Is this player online on Hypixel\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"uuid":{"description":"Minecraft account UUID of the player, with or without dashes, for example '069a79f444e94726a5befca90e38aaf5'.","maxLength":40,"title":"Uuid","type":"string"}},"required":["uuid"],"title":"get_player_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/get_guild":{"post":{"operationId":"get_guild","summary":"Get a guild by guild id, by a member's UUID or by guild name (give exactly one): name, description, members, ranks and e","description":"Get a guild by guild id, by a member's UUID or by guild name (give exactly one): name, description, members, ranks and experience. The full guild object is returned and can be large. Use for \"Which Hypixel guild is this player in and who are its members\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Guild id (24 hex characters).","title":"Id"},"player":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"UUID of a guild member.","title":"Player"},"name":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Guild name, matched exactly.","title":"Name"}},"title":"get_guildArguments","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_skyblock_profiles":{"post":{"operationId":"list_skyblock_profiles","summary":"List a player's SkyBlock profiles with profile id, name, game mode, whether it is the selected profile and the coop bank","description":"List a player's SkyBlock profiles with profile id, name, game mode, whether it is the selected profile and the coop bank balance. Needs the player to have API access enabled in game. Use for \"What SkyBlock profiles does this player have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"uuid":{"description":"Minecraft account UUID of the player, with or without dashes, for example '069a79f444e94726a5befca90e38aaf5'.","maxLength":40,"title":"Uuid","type":"string"}},"required":["uuid"],"title":"list_skyblock_profilesArguments","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_skyblock_auctions":{"post":{"operationId":"list_skyblock_auctions","summary":"List active SkyBlock auction house listings, one page at a time, with item, category, rarity tier, starting and highest ","description":"List active SkyBlock auction house listings, one page at a time, with item, category, rarity tier, starting and highest bid and end time. Use for \"What is on the SkyBlock auction house right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"}},"title":"list_skyblock_auctionsArguments","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_skyblock_auctions":{"post":{"operationId":"find_skyblock_auctions","summary":"Look up SkyBlock auctions by auction UUID, by the seller's player UUID or by profile UUID (give exactly one). Use for \"W","description":"Look up SkyBlock auctions by auction UUID, by the seller's player UUID or by profile UUID (give exactly one). Use for \"What auctions has this SkyBlock player listed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"uuid":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Auction UUID.","title":"Uuid"},"player":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Seller's player UUID.","title":"Player"},"profile":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"SkyBlock profile UUID.","title":"Profile"}},"title":"find_skyblock_auctionsArguments","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_skyblock_firesales":{"post":{"operationId":"get_skyblock_firesales","summary":"List active and upcoming SkyBlock fire sales with item, start and end time, amount and price. Use for \"Are there any Sky","description":"List active and upcoming SkyBlock fire sales with item, start and end time, amount and price. Use for \"Are there any SkyBlock fire sales coming up\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_skyblock_firesalesArguments","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_player_counts":{"post":{"operationId":"get_player_counts","summary":"Show how many players are online on Hypixel in total and per game. Use for \"How many people are playing Hypixel right no","description":"Show how many players are online on Hypixel in total and per game. Use for \"How many people are playing Hypixel right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_player_countsArguments","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_punishment_stats":{"post":{"operationId":"get_punishment_stats","summary":"Show network punishment statistics: Watchdog and staff bans in the last minute, rolling day and in total. Use for \"How m","description":"Show network punishment statistics: Watchdog and staff bans in the last minute, rolling day and in total. Use for \"How many bans has Hypixel Watchdog issued today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_punishment_statsArguments","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_active_houses":{"post":{"operationId":"list_active_houses","summary":"List the currently active public Housing houses with name, owner, creation time, players inside and cookie count. Use fo","description":"List the currently active public Housing houses with name, owner, creation time, players inside and cookie count. Use for \"Which Hypixel housing worlds are popular right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_active_housesArguments","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_player_houses":{"post":{"operationId":"list_player_houses","summary":"List the public Housing houses owned by a player with name, creation time, players and cookie count. Use for \"What publi","description":"List the public Housing houses owned by a player with name, creation time, players and cookie count. Use for \"What public houses does this Hypixel player own\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"player":{"description":"UUID of the player.","maxLength":40,"title":"Player","type":"string"}},"required":["player"],"title":"list_player_housesArguments","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}}}}