Hypixel Public API (v1)

Download OpenAPI specification:Download

Introduction

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

Limits

API keys have a default rate limit of 120 requests per minute. If you require a higher limit please contact us via our support desk with an explanation for the increased limit and your current API key. Any abuse of the API or intentions to bypass this limit ( such as with multiple API keys) will lead to your API key being reset or banned.

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

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

Notes

  • Friendly names are what is displayed to the user when referencing the name.
  • Type names or ids are used when the API references a specific GameType.

Other 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 (i.e. = will be displayed as =), and some programming languages may have silent defects when interpreting the string.

Authentication

ApiKey

Can be obtained by joining the Minecraft server mc.hypixel.net and using the command /api.

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

API

API Key Information

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "record": {
    }
}

Player Data

Data of a specific player, including game stats

Authorizations:
query Parameters
uuid
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "player": {
    }
}

The friends of a specific player

Authorizations:
query Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "uuid": "ad8fefaa8351454bb739a4eaa872173f",
  • "records": [
    ]
}

The recently played games of a specific player

Authorizations:
query Parameters
uuid
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "games": [
    ]
}

The current online status of a specific player

Authorizations:
query Parameters
uuid
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "uuid": "ad8fefaa8351454bb739a4eaa872173f",
  • "session": {
    }
}

Retrieve a Guild by a player, id, or name

Authorizations:
query Parameters
id
string <objectid>
player
string <uuid>
name
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "guild": { }
}

Resources

Achievements

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "lastUpdated": 0,
  • "achievements": { }
}

Challenges

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "lastUpdated": 0,
  • "challenges": { }
}

Quests

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "lastUpdated": 0,
  • "quests": { }
}

Achievements

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "lastUpdated": 0,
  • "one_time": { },
  • "tiered": { }
}

Permissions

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "lastUpdated": 0,
  • "permissions": { }
}

SkyBlock

Collections

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "lastUpdated": 0,