Read-only REST API exposing player, guild, recent games, online status, server counts, boosters, leaderboards, punishment statistics, housing, and the full SkyBlock economy (auctions, bazaar, profiles, museum, garden, bingo, fire sales) for the Hypixel Minecraft network. All endpoints are HTTP GET, JSON, and authenticated with an API key issued via the Hypixel Developer Dashboard.
openapi: 3.0.3
info:
title: Hypixel Public API
x-logo:
url: https://api.hypixel.net/assets/images/logo.png
altText: Hypixel Logo
href: '#'
description: "# Introduction\nThis is the official Hypixel API documentation. [Hypixel Website](https://hypixel.net/) - [GitHub Repo](https://github.com/HypixelDev/PublicAPI) - [API Help Forum](https://hypixel.net/forums/api-help.111/)\n\
\nAll use of the API must conform to the [API policies](https://developer.hypixel.net/policies), violation of these policies may lead to applications being revoked or users banned from the API.\n##
Limits\nAPI keys are limited to a maximum amount of requests per 5 minute intervals. These limits will depend on the type of application that the key is assigned to.\n\nEndpoints which require the use
of an API key will also respond with headers to assist with managing the rate limit:\n- 'RateLimit-Limit' - The limit of requests per minute for the provided API key.\n- 'RateLimit-Remaining' - The
remaining amount of requests allowed for the current minute.\n- 'RateLimit-Reset' - The amount of seconds until the next minute and the reset of the API key usages.\n\n## GameTypes\n| ID | Type Name\
\ | Database Name | Clean Name |\n |----|----------------|---------------|----------------------|\n | 2 | QUAKECRAFT | Quake | Quake |\n | 3 | WALLS \
\ | Walls | Walls |\n | 4 | PAINTBALL | Paintball | Paintball |\n | 5 | SURVIVAL_GAMES | HungerGames | Blitz Survival Games |\n | 6 | TNTGAMES \
\ | TNTGames | TNT Games |\n | 7 | VAMPIREZ | VampireZ | VampireZ |\n | 13 | WALLS3 | Walls3 | Mega Walls |\n | 14 | ARCADE \
\ | Arcade | Arcade |\n | 17 | ARENA | Arena | Arena |\n | 20 | UHC | UHC | UHC Champions |\n | 21 | MCGO \
\ | MCGO | Cops and Crims |\n | 23 | BATTLEGROUND | Battleground | Warlords |\n | 24 | SUPER_SMASH | SuperSmash | Smash Heroes |\n | 25 | GINGERBREAD \
\ | GingerBread | Turbo Kart Racers |\n | 26 | HOUSING | Housing | Housing |\n | 51 | SKYWARS | SkyWars | SkyWars |\n | 52 | TRUE_COMBAT |
TrueCombat | Crazy Walls |\n | 54 | SPEED_UHC | SpeedUHC | Speed UHC |\n | 55 | SKYCLASH | SkyClash | SkyClash |\n | 56 | LEGACY | Legacy\
\ | Classic Games |\n | 57 | PROTOTYPE | Prototype | Prototype |\n | 58 | BEDWARS | Bedwars | Bed Wars |\n | 59 | MURDER_MYSTERY | MurderMystery
| Murder Mystery |\n | 60 | BUILD_BATTLE | BuildBattle | Build Battle |\n | 61 | DUELS | Duels | Duels |\n | 63 | SKYBLOCK | SkyBlock | SkyBlock\
\ |\n | 64 | PIT | Pit | Pit |\n | 65 | REPLAY | Replay | Replay |\n | 67 | SMP | SMP | SMP \
\ |\n | 68 | WOOL_GAMES | WoolGames | Wool Wars |\n\n### Storage\nGames store their respective stats and data in a Player's `stats` collection. The game's specific data
is held within a JSON object named after it's `Database Name` (seen above.)\n### GameType Notes\n* Clean names are what is displayed to the user when referencing the name.\n* Database names or IDs are
used when the API references a specific GameType.\n## Notes\n\n### Date and Time\nGenerally dates are stored as a Unix Epoch times in milliseconds.\n### Response Format\nResponses are served in JSON
format.\n### UUID Parameters\nAll uuid parameters support both dashed and undashed versions.\n### SkyBlock items and inventories\nItems and inventory data are stored as a base64 encoded string containing
gzipped nbt data.\nIf a method is missing important information about an item or inventory, you should try checking this!\n>Note: the base64 string may contain a unicode escape for non-alphabetical
symbols, and some programming languages may have silent defects when interpreting the string. \n\n# Authentication\n\n<!-- ReDoc-Inject: <security-definitions> -->"
version: v2
termsOfService: https://hypixel.net/tos
contact:
name: Hypixel Support
url: https://developer.hypixel.net
x-jentic-source-url: https://api.hypixel.net/
x-generated-from: jentic-public-apis
x-last-validated: '2026-05-30'
servers:
- url: https://api.hypixel.net
components:
securitySchemes:
ApiKey:
type: apiKey
in: header
name: API-Key
description: Obtained via the [Hypixel Developer Dashboard](https://developer.hypixel.net) when creating an application. You can also request higher limits for production applications in this
dashboard.
responses:
DataMissing:
description: Some data is missing, this is usually a field.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
cause:
type: string
example: Missing one or more fields [...]
InvalidKey:
description: Access is forbidden, usually due to an invalid API key being used.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
cause:
type: string
example: Invalid API key
RateLimited:
description: A request limit has been reached, usually this is due to the limit on the key being reached but can also be triggered by a global throttle.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
cause:
type: string
example: Key throttle
throttle:
type: boolean
example: true
global:
type: boolean
description: When this boolean exists and is true, the throttle occurring is a global throttle applied to all users
example: true
InvalidPage:
description: The page provided is invalid.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
cause:
type: string
example: Invalid page
MissingPage:
description: The page provided does not exist.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
cause:
type: string
example: Page not found
MalformedData:
description: Some data provided is invalid.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
cause:
type: string
example: Malformed UUID
NotPopulated:
description: The data is not yet populated and should be available shortly
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
cause:
type: string
example: Leaderboard data has not yet been populated
NoResult:
description: The request responded with no result.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
cause:
type: string
example: No result was found
schemas:
Booster:
properties:
_id:
type: string
format: objectid
example: 5fcbf9d9d295e80a766f3b14
purchaserUuid:
type: string
format: uuid
example: ad8fefaa8351454bb739a4eaa872173f
amount:
type: number
example: 1.0
originalLength:
type: integer
example: 42
length:
type: integer
example: 42
gameType:
type: integer
example: 42
dateActivated:
type: integer
format: int64
example: 1748544600000
ActiveBooster:
allOf:
- $ref: '#/components/schemas/Booster'
- type: object
properties:
stacked:
type: array
nullable: true
items:
type: string
description: UUID of the player in a dashed format
format: uuid
example: ad8fefaa-8351-454b-b739-a4eaa872173f
QueuedBooster:
allOf:
- $ref: '#/components/schemas/Booster'
- type: object
properties:
stacked:
type: boolean
nullable: true
SkyBlockAuction:
properties:
_id:
type: string
format: objectid
example: 5fcbf9d9d295e80a766f3b14
uuid:
type: string
format: uuid
example: ad8fefaa8351454bb739a4eaa872173f
auctioneer:
type: string
format: uuid
example: ad8fefaa8351454bb739a4eaa872173f
profile_id:
type: string
format: uuid
example: ad8fefaa8351454bb739a4eaa872173f
coop:
type: array
items:
type: string
format: uuid
start:
type: number
format: int64
example: 1.0
end:
type: number
format: int64
example: 1.0
item_name:
type: string
example: ExamplePlayer
item_lore:
type: string
example: example
extra:
type: string
example: example
category:
type: string
example: example
tier:
type: string
example: example
starting_bid:
type: number
example: 1.0
item_bytes:
type: object
properties:
type:
type: number
example: 1.0
data:
type: string
example: example
claimed:
type: boolean
example: true
claimed_bidders:
type: array
highest_bid_amount:
type: number
example: 1.0
bids:
type: array
items:
type: object
properties:
auction_id:
type: string
format: uuid
example: ad8fefaa8351454bb739a4eaa872173f
bidder:
type: string
format: uuid
example: ad8fefaa8351454bb739a4eaa872173f
profile_id:
type: string
format: uuid
example: ad8fefaa8351454bb739a4eaa872173f
amount:
type: number
example: 1.0
timestamp:
type: number
format: int64
example: 1.0
example:
uuid: 409a1e0f261a49849493278d6cd9305a
auctioneer: 347ef6c1daac45ed9d1fa02818cf0fb6
profile_id: 347ef6c1daac45ed9d1fa02818cf0fb6
coop:
- 347ef6c1daac45ed9d1fa02818cf0fb6
start: 1573760802637
end: 1573761102637
item_name: Azure Bluet
item_lore: "§f§lCOMMON"
extra: Azure Bluet Red Rose
category: blocks
tier: COMMON
starting_bid: 1
item_bytes:
type: 0
data:
H4sIAAAAAAAAAB2NQQqCQBhGv1ErHaKu0KoLtGtnarRIhTpA/OGfDIwZ4wxUF/IeHiyyto/3eBKIIJQEIDx4qsJaYJK07m6FhG+p9hEdVMV7TXU3Wh+JWaW6h6ZXhODYGg5/LeZDfxt6nZR5XhYhgoIaxmKE8dsZXu20YwuJZfa0hmJrjbo6y134f8pTll5O5TnbbgAP05Qaqhk+8AVIrd2eoAAAAA==
claimed: true
claimed_bidders: []
highest_bid_amount: 7607533
bids:
- auction_id: 409a1e0f261a49849493278d6cd9305a
bidder: 99748e629dee463892f68abf3a780094
profile_id: 99748e629dee463892f68abf3a780094
amount: 7607533
timestamp: 1573760824844
SkyBlockProfile:
properties:
profile_id:
type: string
format: uuid
example: ad8fefaa8351454bb739a4eaa872173f
members:
description: A map of member UUIDs to member profiles objects
type: object
properties:
player_id:
type: string
format: uuid
example: ad8fefaa8351454bb739a4eaa872173f
profile:
type: object
properties:
deletion_notice:
description: If this field exists, the member profile is marked as deleted
nullable: true
type: object
properties:
timestamp:
type: integer
format: int64
example: 1748544600000
cute_name:
description: The cute name of the profile, only provided on the profiles endpoint
nullable: true
type: string
example: ExamplePlayer
selected:
description: Whether or not this is the currently selected profile, only provided on the profiles endpoint
nullable: true
type: boolean
example: true
community_upgrades:
nullable: true
type: object
banking:
description: Information about the bank account for this profile, only present if the API banking setting is enabled
nullable: true
type: object
properties:
balance:
type: number
format: double
example: 1.0
transactions:
type: array
items:
type: object
properties:
timestamp:
type: integer
format: int64
example: 1748544600000
action:
type: string
enum:
- DEPOSIT
- WITHDRAW
example: DEPOSIT
initiator_name:
type: string
example: ExamplePlayer
amount:
type: number
format: double
example: 1.0
game_mode:
description: The SkyBlock game mode of the profile, not present if normal mode
nullable: true
type: string
enum:
- ironman
- island
- bingo
example: ironman
SkyBlockItem:
properties:
id:
description: The unique identifier for this item
type: string
example: '500123'
material:
description: The Bukkit material enum value for the item
type: string
example: example
name:
description: The name of the item
type: string
example: ExamplePlayer
tier:
description: The rarity tier of the item
type: string
enum:
- COMMON
- UNCOMMON
- RARE
- EPIC
- LEGENDARY
- MYTHIC
- SUPREME
- SPECIAL
- VERY_SPECIAL
example: COMMON
color:
description: The color metadata to be applied to an item, usually leather armor pieces
pattern: ^(?:(?:^|,\s*)([01]?\d\d?|2[0-4]\d|25[0-5])){3}$
type: string
example: example
skin:
description: The skin value for a skull based item
type: string
example: example
example:
material: LEATHER_CHESTPLATE
color: 255,215,0
name: Farm Armor Chestplate
category: CHESTPLATE
tier: RARE
stats:
DEFENSE: 75
HEALTH: 20
npc_sell_price: 5200
id: FARM_ARMOR_CHESTPLATE
SkyBlockMuseum:
properties:
value:
type: integer
format: int64
example: 1748544600000
appraisal:
type: boolean
example: true
items:
type: object
special:
type: array
properties:
donated_time:
type: integer
format: int64
example: 1748544600000
items:
type: object
Game:
description: Information about a specific game. When a field is not present you should fallback to the provided default if there is one, required fields will always exist.
required:
- id
- name
- databaseName
properties:
id:
type: integer
description: The backend ID of the game.
example: 1
name:
type: string
description: The display name of the game.
example: Bed Wars
databaseName:
type: string
description: The key used for database storage, such as for stats.
example: Bedwars
modeNames:
type: object
description: A map of mode key to display name
example:
solo_normal: Solo
team_normal: Doubles
retired:
type: boolean
description: True if the game is retired and no longer playable.
default: false
example: false
legacy:
type: boolean
description: True if the game is legacy and part of the Classic Lobby.
default: false
example: false
example:
id: 58
name: Bed Wars
databaseName: Bedwars
modeNames:
BEDWARS_TWO_FOUR: 4v4
BEDWARS_EIGHT_ONE: Solo
SkyBlockFireSale:
properties:
item_id:
description: The SkyBlock item ID for this sale
type: string
example: '500123'
start:
description: The start time in unix milliseconds for the sale
type: number
example: 1.0
end:
description: The end time in unix milliseconds for the sale
type: number
example: 1.0
amount:
description: The amount of items available for this sale
type: integer
example: 42
price:
description: The price in Gems for this sale
type: integer
example: 42
SkyBlockGarden:
description: Information about a player's SkyBlock garden, the only guaranteed field is the `uuid` field.
required:
- uuid
properties:
uuid:
type: string
format: uuid
description: The UUID of the profile for this garden.
example: ad8fefaa8351454bb739a4eaa872173f
commission_data:
type: object
properties:
visits:
type: object
description: A map of visitor identifier to visit count
example:
jerry: 1
jacob: 2
andrew: 3
completed:
type: object
description: A map of visitor identifier to completed count
example:
jerry: 1
jacob: 1
andrew: 2
total_completed:
type: integer
format: int32
example: 42
unique_npcs_served:
type: integer
format: int32
example: 42
composter_data:
type: object
example:
organic_matter: 1772.8
fuel_units: 17000
compost_units: 0
compost_items: 2
conversion_ticks: 300
last_save: 1721039418436
upgrades:
speed: 25
multi_drop: 25
fuel_cap: 22
organic_matter_cap: 25
cost_reduction: 25
active_commissions:
type: object
example:
liam:
requirement:
- original_item: NETHER_STALK
original_amount: 93995
item: MUTANT_NETHER_STALK
amount: 4
status: NOT_STARTED
position: 1
lumberjack:
requirement:
- original_item: POTATO_ITEM
original_amount: 81380
item: ENCHANTED_BAKED_POTATO
amount: 3
status: NOT_STARTED
position: 2
oringo:
requirement:
- original_item: WHEAT
original_amount: 26798
item: ENCHANTED_HAY_BLOCK
amount: 21
status: NOT_STARTED
position: 3
rhys:
requirement:
- original_item: JACK_O_LANTERN
original_amount: 512
item: JACK_O_LANTERN
amount: 512
status: NOT_STARTED
position: 4
fear_mongerer:
requirement:
- original_item: PUMPKIN
original_amount: 27709
item: POLISHED_PUMPKIN
amount: 1
status: NOT_STARTED
position: 5
extra_rewards:
- candy: PURPLE_CANDY
resources_collected:
type: object
description: A map of resource ID to amount collected
example:
WHEAT: 100
POTATO_ITEM: 100
INK_SACK:3: 100
crop_upgrade_levels:
type: object
example:
WHEAT: 1
POTATO_ITEM: 2
INK_SACK:3: 3
unlocked_plots_ids:
type: array
items:
type: string
example:
- beginner_1
- intermediate_3
garden_experience:
type: integer
format: double
example: 42
unlocked_barn_skins:
type: array
items:
type: string
selected_barn_skin:
type: string
example: example
HousingHouse:
description: Information about a player's house.
required:
- uuid
- owner
- name
- createdAt
- players
- cookies
properties:
uuid:
type: string
format: uuid
description: The UUID of this house.
example: ad8fefaa8351454bb739a4eaa872173f
owner:
type: string
format: uuid
description: The UUID of the owner of this house.
example: ad8fefaa8351454bb739a4eaa872173f
name:
type: string
nullable: true
description: The name of this house, may contain Minecraft color symbols.
example: ExamplePlayer
createdAt:
type: number
format: int64
description: The time this house was created.
example: 1.0
players:
type: number
format: int32
description: The number of players in this house.
example: 1.0
cookies:
type: object
properties:
current:
type: number
format: int32
description: The current amount of cookies that this house has for the current week.
example: 1.0
paths:
/v2/player:
get:
summary: Hypixel Data of a Specific Player, Including Game Stats
tags:
- Player Data
security:
- ApiKey: []
parameters:
- in: query
name: uuid
schema:
type: string
required: true
example: ad8fefaa8351454bb739a4eaa872173f
description: The uuid parameter.
responses:
'200':
description: Get player's data
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
player:
type: object
properties:
uuid:
type: string
example: 3fa85f6457174562b3fc2c963f66afa6
displayname:
type: string
nullable: true
rank:
type: string
nullable: true
enum:
- ADMIN
- MODERATOR
- HELPER
- NORMAL
packageRank:
type: string
nullable: true
enum:
- MVP_PLUS
- MVP
- VIP_PLUS
- VIP
- NONE
newPackageRank:
type: string
nullable: true
enum:
- MVP_PLUS
- MVP
- VIP_PLUS
- VIP
- NONE
monthlyPackageRank:
type: string
nullable: true
enum:
- SUPERSTAR
- NONE
firstLogin:
type: number
nullable: true
lastLogin:
type: number
nullable: true
lastLogout:
type: number
nullable: true
stats:
type: object
nullable: true
examples:
GetPlayer200Example:
summary: Default getPlayer 200 response
x-microcks-default: true
value:
success: true
player:
uuid: 3fa85f6457174562b3fc2c963f66afa6
displayname: ExamplePlayer
rank: ADMIN
packageRank: MVP_PLUS
newPackageRank: MVP_PLUS
monthlyPackageRank: SUPERSTAR
'400':
$ref: '#/components/responses/DataMissing'
'403':
$ref: '#/components/responses/InvalidKey'
'429':
$ref: '#/components/responses/RateLimited'
operationId: getPlayer
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
description: Data of a specific player, including game stats
/v2/recentgames:
get:
summary: Hypixel The Recently Played Games of a Specific Player
tags:
- Player Data
security:
- ApiKey: []
parameters:
- in: query
name: uuid
schema:
type: string
required: true
example: ad8fefaa8351454bb739a4eaa872173f
description: The uuid parameter.
responses:
'200':
description: Get player's recent game
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
uuid:
type: string
format: uuid
games:
type: array
items:
type: object
properties:
date:
type: number
format: int64
gameType:
type: string
mode:
type: string
map:
type: string
ended:
type: number
format: int64
examples:
GetRecentgames200Example:
summary: Default getRecentgames 200 response
x-microcks-default: true
value:
success: true
uuid: ad8fefaa8351454bb739a4eaa872173f
games:
- date: 1.0
gameType: example
mode: example
map: example
ended: 1.0
'400':
$ref: '#/components/responses/DataMissing'
'403':
$ref: '#/components/responses/InvalidKey'
'422':
$ref: '#/components/responses/MalformedData'
'429':
$ref: '#/components/responses/RateLimited'
operationId: getRecentgames
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
description: The recently played games of a specific player
/v2/status:
get:
summary: Hypixel The Current Online Status of a Specific Player
tags:
- Player Data
security:
- ApiKey: []
parameters:
- in: query
name: uuid
schema:
type: string
required: true
example: ad8fefaa8351454bb739a4eaa872173f
description: The uuid parameter.
responses:
'200':
description: Get player status
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
uuid:
type: string
format: uuid
example: ad8fefaa8351454bb739a4eaa872173f
session:
type: object
properties:
online:
type: boolean
gameType:
type: string
mode:
type: string
map:
type: string
examples:
GetStatus200Example:
summary: Default getStatus 200 response
x-microcks-default: true
value:
success: true
uuid: ad8fefaa8351454bb739a4eaa872173f
session:
online: true
gameType: example
mode: example
map: example
'400':
$ref: '#/components/responses/DataMissing'
'403':
$ref: '#/components/responses/InvalidKey'
'429':
$ref: '#/components/responses/RateLimited'
operationId: getStatus
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
description: The current online status of a specific player
/v2/guild:
get:
summary: Hypixel Retrieve a Guild by a Player, Id, or Name
tags:
- Player Data
security:
- ApiKey: []
parameters:
- in: query
name: id
schema:
type: string
format: objectid
example: 5fcbf9d9d295e80a766f3b14
description: The id parameter.
- in: query
name: player
schema:
type: string
format: uuid
example: ad8fefaa8351454bb739a4eaa872173f
description: The player parameter.
- in: query
name: name
schema:
type: string
example: ExamplePlayer
description: The name parameter.
responses:
# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hypixel/refs/heads/main/openapi/hypixel-public-api-openapi.yml