Hypixel Public API (v2)

Download OpenAPI specification:Download

URL: https://developer.hypixel.net Terms of Service

Introduction

This is the official Hypixel API documentation. Hypixel Website - GitHub Repo - API Help Forum

All use of the API must conform to the API policies, violation of these policies may lead to applications being revoked or users banned from the API.

Limits

API 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.

Endpoints which require the use of an API key will also respond with headers to assist with managing the rate limit:

'RateLimit-Limit' - The limit of requests per minute for the provided API key.
'RateLimit-Remaining' - The remaining amount of requests allowed for the current minute.
'RateLimit-Reset' - The amount of seconds until the next minute and the reset of the API key usages.

GameTypes

ID	Type Name	Database Name	Clean Name
2	QUAKECRAFT	Quake	Quake
3	WALLS	Walls	Walls
4	PAINTBALL	Paintball	Paintball
5	SURVIVAL_GAMES	HungerGames	Blitz Survival Games
6	TNTGAMES	TNTGames	TNT Games
7	VAMPIREZ	VampireZ	VampireZ
13	WALLS3	Walls3	Mega Walls
14	ARCADE	Arcade	Arcade
17	ARENA	Arena	Arena
20	UHC	UHC	UHC Champions
21	MCGO	MCGO	Cops and Crims
23	BATTLEGROUND	Battleground	Warlords
24	SUPER_SMASH	SuperSmash	Smash Heroes
25	GINGERBREAD	GingerBread	Turbo Kart Racers
26	HOUSING	Housing	Housing
51	SKYWARS	SkyWars	SkyWars
52	TRUE_COMBAT	TrueCombat	Crazy Walls
54	SPEED_UHC	SpeedUHC	Speed UHC
55	SKYCLASH	SkyClash	SkyClash
56	LEGACY	Legacy	Classic Games
57	PROTOTYPE	Prototype	Prototype
58	BEDWARS	Bedwars	Bed Wars
59	MURDER_MYSTERY	MurderMystery	Murder Mystery
60	BUILD_BATTLE	BuildBattle	Build Battle
61	DUELS	Duels	Duels
63	SKYBLOCK	SkyBlock	SkyBlock
64	PIT	Pit	Pit
65	REPLAY	Replay	Replay
67	SMP	SMP	SMP
68	WOOL_GAMES	WoolGames	Wool Wars

Storage

Games 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.)

GameType Notes

Clean names are what is displayed to the user when referencing the name.
Database names or IDs are used when the API references a specific GameType.

Notes

Date and Time

Generally dates are stored as a Unix Epoch times in milliseconds.

Response Format

Responses are served in JSON format.

UUID Parameters

All uuid parameters support both dashed and undashed versions.

SkyBlock items and inventories

Items and inventory data are stored as a base64 encoded string containing gzipped nbt data. If a method is missing important information about an item or inventory, you should try checking this!

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.

Authentication

ApiKey

Obtained via the Hypixel Developer Dashboard when creating an application. You can also request higher limits for production applications in this dashboard.

Security Scheme Type	API Key
Header parameter name:	API-Key

Player Data

Data of a specific player, including game stats

Authorizations:

ApiKey

query Parameters

uuid

required

string

Responses

Response samples

200
400
403
429

Content type

application/json

{"success": true,
"player": {"uuid": "3fa85f6457174562b3fc2c963f66afa6",
"displayname": "string",
"rank": "ADMIN",
"packageRank": "MVP_PLUS",
"newPackageRank": "MVP_PLUS",
"monthlyPackageRank": "SUPERSTAR",
"firstLogin": 0,
"lastLogin": 0,
"lastLogout": 0,
"stats": { }
}
}

The recently played games of a specific player

Authorizations:

ApiKey

query Parameters

uuid

required

string

Responses

Response samples

200
400
403
422
429

Content type

application/json

{"success": true,
"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
"games": [{"date": 0,
"gameType": "string",
"mode": "string",
"map": "string",
"ended": 0
}
]
}

The current online status of a specific player

Authorizations:

ApiKey

query Parameters

uuid

required

string

Responses

Response samples

200
400
403
429

Content type

application/json

{"success": true,
"uuid": "ad8fefaa8351454bb739a4eaa872173f",
"session": {"online": true,
"gameType": "string",
"mode": "string",
"map": "string"
}
}

Retrieve a Guild by a player, id, or name

Authorizations:

ApiKey

query Parameters

id	string <objectid>
player	string <uuid>
name	string

Responses

Response samples

200
400
403
429

Content type

application/json

{"success": true,
"guild": { }
}

Resources

Game Information

Returns information about Hypixel Games. This endpoint is in early development and we are working to add more information when possible HypixelDev/PublicAPI#197

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 0,
"games": {"property1": {"id": 58,
"name": "Bed Wars",
"databaseName": "Bedwars",
"modeNames": {"BEDWARS_TWO_FOUR": "4v4",
"BEDWARS_EIGHT_ONE": "Solo"
}
},
"property2": {"id": 58,
"name": "Bed Wars",
"databaseName": "Bedwars",
"modeNames": {"BEDWARS_TWO_FOUR": "4v4",
"BEDWARS_EIGHT_ONE": "Solo"
}
}
}
}

Achievements

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 0,
"achievements": { }
}

Challenges

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 0,
"challenges": { }
}

Quests

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 0,
"quests": { }
}

Guild Achievements

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 0,
"one_time": { },
"tiered": { }
}

Vanity Pets

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 0,
"types": { },
"rarities": { }
}

Vanity Companions

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 0,
"types": { },
"rarities": { }
}

SkyBlock

Collections

Information regarding Collections in the SkyBlock game.

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 0,
"version": "0.11.22",
"collections": { }
}

Skills

Information regarding skills in the SkyBlock game.

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 0,
"version": "0.11.22",
"skills": { }
}

Items

Information regarding items in the SkyBlock game.

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 0,
"items": [{"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"
}
]
}

Election and Mayor

Information regarding the current mayor and ongoing election in SkyBlock.

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 0,
"mayor": { },
"current": { }
}

Current Bingo Event

Information regarding the current bingo event and its goals.

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 0,
"id": 27,
"name": "March 2024",
"start": 1709269200000,
"end": 1709874000000,
"modifier": "NORMAL",
"goals": [{"id": "string",
"name": "string",
"lore": "string",
"fullLore": [ ],
"tiers": [0
],
"progress": 0,
"requiredAmount": 0
}
]
}

News

Authorizations:

ApiKey

Responses

Response samples

200
403
429

Content type

application/json

{"success": true,
"items": [{"item": {"material": "DIAMOND"
},
"link": "https://hypixel.net",
"title": "SkyBlock v0.11",
"text": "15th January 2021"
}
]
}

Request auction(s) by the auction UUID, player UUID, or profile UUID.

Returns the auctions selected by the provided query. Only one query parameter can be used in a single request, and cannot be filtered by multiple.

Authorizations:

ApiKey

query Parameters

uuid	string The auction UUID that you wish to request
player	string The player UUID that you wish to request
profile	string The profile UUID that you wish to request

Responses

Response samples

200
400
403
422
429

Content type

application/json

{"success": true,
"auctions": [{"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
}
]
}
]
}

Active auctions

Returns the currently active auctions sorted by last updated first and paginated.

query Parameters

page	number Default: 0

Responses

Response samples

200
404
422
503

Content type

application/json

{"success": true,
"page": 0,
"totalPages": 32,
"totalAuctions": 31267,
"lastUpdated": 1571065561345,
"auctions": [{"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
}
]
}
]
}

Recently ended auctions

SkyBlock auctions which ended in the last 60 seconds.

Responses

Response samples

200

Content type

application/json

{"success": true,
"lastUpdated": 1607456463916,
"auctions": [{"auction_id": "015fe0c67e6041e69797bbe0c2725a21",
"seller": "fc76242bf64a4698ae0ebc136d900929",
"seller_profile": "85b96cd3e73e4580b8379162ec059141",
"buyer": "c1eff55de0d24ec6b44848799e9323ba",
"buyer_profile": "a3e1c076533a40a58085e7f43a598bf3",
"timestamp": 1607456400329,
"price": 190000,
"bin": true,
"item_bytes": "H4sIAAAAAAAAAEWR3W7TQBCFx2mBxKgtSH2ArUACZKL6L9jtndUYBdHQyGlV7qq1PXZX9U+03kB6yYNw7ffwo/AgiHEC4m7mmz1nz87qACPQhA4A2gAGItUGGjy5qNeV0nTYUzzX4PlNFUvkDzwuUNuD0Uyk+LHgeUOi3zo8S0WzKvjjCPYva4lDoofwsmu9KS95juesaxPDN+GY0FJJrHJ1v4PWxKTDAfGQy4rQB8M2WVKLqqHGy2RdsrKuGoWSPYiiaNjbS/yGBQ3RMo3+TF0Vj+/I5NXWj+2u7Acr0hCbmGbfbdWgd60/5xtmOBM4JPq5p9sofY43W4tfP3+wfyn/++Bfn+91nYJBxS0VlLQoMFGCIvYu6FnvXcenindtMQ++htMT8u11dPH1vWiYUFiyhFcsRiYxq2WO6Qm86NozUkRBFLLl7VU0HcL+F14iHNAg4rRuyYINgg5H4UZJHiglRbxW2AxhVEuRi+qa53CwnF0t7hY30cUsWIbD/jdBj4JP0zC6ozBkul4Teu34Tua7vj124tQduz73xtxOvbGVoZtMbN/xnIyMlSixUbxcwZFln/qn9DX2ue2wxRxgAE93q6b3wR9BYJa/RAIAAA=="
}
]
}

Bazaar

Returns the list of products along with their sell summary, buy summary and quick status.

Product Description

The returned product info has 3 main fields:

buy_summary
sell_summary
quick_status

buy_summary and sell_summary are the current top 30 orders for each transaction type (in-game example: Stock of Stonks).

quick_status is a computed summary of the live state of the product (used for advanced mode view in the bazaar):

sellVolume and buyVolume are the sum of item amounts in all orders.
- sellPrice and buyPrice are the weighted average of the top 2% of orders by volume.
- movingWeek is the historic transacted volume from last 7d + live state.
- sellOrders and buyOrders are the count of active orders.

Responses

Response samples

200
503

Content type

application/json

{"success": true,
"lastUpdated": 1590854517479,
"products": {"INK_SACK:3": {"product_id": "INK_SACK:3",
"sell_summary": [{"amount": 20569,
"pricePerUnit": 4.2,
"orders": 1
},
{"amount": 140326,
"pricePerUnit": 3.8,
"orders": 2
}
],
"buy_summary": [{"amount": 640,
"pricePerUnit": 4.8,
"orders": 1
},
{"amount": 640,
"pricePerUnit": 4.9,
"orders": 1
},
{"amount": 25957,
"pricePerUnit": 5,
"orders": 3
}
],
"quick_status": {"productId": "INK_SACK:3",
"sellPrice": 4.2,
"sellVolume": 409855,
"sellMovingWeek": 8301075,
"sellOrders": 11,
"buyPrice": 4.99260315136572,
"buyVolume": 1254854,
"buyMovingWeek": 5830656,
"buyOrders": 85
}
}
}
}

Profile by UUID

SkyBlock profile data, such as stats, objectives etc. The data returned can differ depending on the players in-game API settings.

Authorizations:

ApiKey

query Parameters

profile

string <uuid>

Responses

Response samples

200
400
403
422
429

Content type

application/json

{"success": true,
"profile": {"profile_id": "bfcb6779-b1f9-41fc-92d7-88f8bc1d12e8",
"members": {"player_id": "f8b23bf6-c56d-4f96-b79c-96d80504663d",
"profile": {"deletion_notice": {"timestamp": 0
}
}
},
"cute_name": "string",
"selected": true,
"community_upgrades": { },
"banking": {"balance": 0,
"transactions": [{"timestamp": 0,
"action": "DEPOSIT",
"initiator_name": "string",
"amount": 0
}
]
},
"game_mode": "ironman"
}
}

Profiles by player

Authorizations:

ApiKey

query Parameters

uuid	string <uuid>

Responses

Response samples

200
400
403
422
429

Content type

application/json

{"success": true,
"profiles": [{"profile_id": "bfcb6779-b1f9-41fc-92d7-88f8bc1d12e8",
"members": {"player_id": "f8b23bf6-c56d-4f96-b79c-96d80504663d",
"profile": {"deletion_notice": {"timestamp": 0
}
}
},
"cute_name": "string",
"selected": true,
"community_upgrades": { },
"banking": {"balance": 0,
"transactions": [{"timestamp": 0,
"action": "DEPOSIT",
"initiator_name": "string",
"amount": 0
}
]
},
"game_mode": "ironman"
}
]
}

Museum data by profile ID

SkyBlock museum data for all members of the provided profile. The data returned can differ depending on the players in-game API settings.

Authorizations:

ApiKey

query Parameters

profile

string <uuid>

Responses

Response samples

200
403
422
429

Content type

application/json

{"success": true,
"profile": {"value": 0,
"appraisal": true,
"items": { },
"special": [ ]
}
}

Garden data by profile ID

SkyBlock garden data for the provided profile.

Authorizations:

ApiKey

query Parameters

profile

string <uuid>

Responses

Response samples

200
403
404
422
429

Content type

application/json

{"success": true,
"garden": {"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
"commission_data": {"visits": {"jerry": 1,
"jacob": 2,
"andrew": 3
},
"completed": {"jerry": 1,
"jacob": 1,
"andrew": 2
},
"total_completed": 0,
"unique_npcs_served": 0
},
"composter_data": {"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": {"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": {"WHEAT": 100,
"POTATO_ITEM": 100,
"INK_SACK:3": 100
},
"crop_upgrade_levels": {"WHEAT": 1,
"POTATO_ITEM": 2,
"INK_SACK:3": 3
},
"unlocked_plots_ids": ["beginner_1",
"intermediate_3"
],
"garden_experience": 0,
"unlocked_barn_skins": ["string"
],
"selected_barn_skin": "string"
}
}

Bingo data by player

Bingo data for participated events of the provided player.

Authorizations:

ApiKey

query Parameters

uuid	string <uuid>

Responses

Response samples

Content type

application/json

{"success": true,
"events": [{"key": 2,
"points": 117,
"completed_goals": [["stat_walk_speed",
"KILL_TRAPPER_MOB"
]
]
}
]
}

Active/Upcoming Fire Sales

Retrieve the currently active or upcoming Fire Sales for SkyBlock.

Responses

Response samples

200

Content type

application/json

{"success": true,
"sales": [{"item_id": "string",
"start": 0,
"end": 0,
"amount": 0,
"price": 0
}
]
}

Housing

The currently active public houses.

This data may be cached for a short period of time.

Authorizations:

ApiKey

Responses

Response samples

200
403
429

Content type

application/json

[{"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
"owner": "534359f7-5407-4b19-ba92-c71c370022a5",
"name": "string",
"createdAt": 0,
"players": 0,
"cookies": {"current": 0
}
}
]

Information about a specific house.

This data may be cached for a short period of time.

Authorizations:

ApiKey

query Parameters

house

required

string

The UUID of the house to get information about.

Responses

Response samples

200
403
404
429

Content type

application/json

{"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
"owner": "534359f7-5407-4b19-ba92-c71c370022a5",
"name": "string",
"createdAt": 0,
"players": 0,
"cookies": {"current": 0
}
}

The public houses for a specific player.

This data may be cached for a short period of time.

Authorizations:

ApiKey

query Parameters

player

string

The UUID of the player to get houses for.

Responses

Response samples

200
403
429

Content type

application/json

[{"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
"owner": "534359f7-5407-4b19-ba92-c71c370022a5",
"name": "string",
"createdAt": 0,
"players": 0,
"cookies": {"current": 0
}
}
]

Other

Active Network Boosters

Authorizations:

ApiKey

Responses

Response samples

200
403
429

Content type

application/json

{"success": true,
"boosters": [{"_id": "string",
"purchaserUuid": "ad8fefaa8351454bb739a4eaa872173f",
"amount": 0,
"originalLength": 0,
"length": 0,
"gameType": 0,
"dateActivated": 0,
"stacked": ["ad8fefaa-8351-454b-b739-a4eaa872173f"
]
}
],
"boosterState": {"decrementing": true
}
}

Current Player Counts

Authorizations:

ApiKey

Responses

Response samples

200
403
429

Content type

application/json

{"success": true,
"playerCount": 0,
"games": {"GAME_TYPE": {"players": 2,
"modes": {"mode_1": 1,
"mode_2": 1
}
}
}
}

Current Leaderboards

Authorizations:

ApiKey

Responses

Response samples

200
403
429
503

Content type

application/json

{"success": true,
"leaderboards": { }
}

Punishment Statistics

Authorizations:

ApiKey

Responses

Response samples

200
403
429
503

Content type

application/json

{"success": true,
"watchdog_lastMinute": 0,
"staff_rollingDaily": 0,
"watchdog_total": 0,
"watchdog_rollingDaily": 0,
"staff_total": 0
}