Hypixel Public API (v2)

Download OpenAPI specification:Download

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:
query Parameters
uuid
required
string

Responses

Response samples

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

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

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

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

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": { }
}

Guild Achievements

Responses

Response samples

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

Vanity Pets

Responses

Response samples

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

Vanity Companions

Responses

Response samples

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

SkyBlock

Collections

Information regarding Collections in the SkyBlock game.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "lastUpdated": 0,
  • "version": "0.11.22",
  • "collections": { }
}

Skills

Information regarding skills in the SkyBlock game.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "lastUpdated": 0,
  • "version": "0.11.22",
  • "skills": { }
}

Items

Information regarding items in the SkyBlock game.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "lastUpdated": 0,
  • "items": [
    ]
}

Election and Mayor

Information regarding the current mayor and ongoing election in SkyBlock.

Responses

Response samples

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

Content type
application/json
{
  • "success": true,
  • "lastUpdated": 0,
  • "id": 27,
  • "name": "March 2024",
  • "start": 1709269200000,
  • "end": 1709874000000,
  • "modifier": "NORMAL",
  • "goals": [
    ]
}

News

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "items": [
    ]
}

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:
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

Content type
application/json
{
  • "success": true,
  • "auctions": [
    ]
}

Active auctions

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

query Parameters
page
number
Default: 0

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "page": 0,
  • "totalPages": 32,
  • "totalAuctions": 31267,
  • "lastUpdated": 1571065561345,
  • "auctions": [
    ]
}

Recently ended auctions

SkyBlock auctions which ended in the last 60 seconds.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "lastUpdated": 1607456463916,
  • "auctions": [
    ]
}

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

Content type
application/json
{
  • "success": true,
  • "lastUpdated": 1590854517479,
  • "products": {
    }
}

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:
query Parameters
profile
string <uuid>

Responses

Response samples

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

Profiles by player

Authorizations:
query Parameters
uuid
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "profiles": [
    ]
}

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:
query Parameters
profile
string <uuid>

Responses

Response samples

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

Garden data by profile ID

SkyBlock garden data for the provided profile.

Authorizations:
query Parameters
profile
string <uuid>

Responses

Response samples

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

Bingo data by player

Bingo data for participated events of the provided player.

Authorizations:
query Parameters
uuid
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "events": [
    ]
}

Active/Upcoming Fire Sales

Retrieve the currently active or upcoming Fire Sales for SkyBlock.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "sales": [
    ]
}

Housing

The currently active public houses.

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

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Information about a specific house.

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

Authorizations:
query Parameters
house
required
string

The UUID of the house to get information about.

Responses

Response samples

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

The public houses for a specific player.

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

Authorizations:
query Parameters
player
string

The UUID of the player to get houses for.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Other

Active Network Boosters

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "boosters": [
    ],
  • "boosterState": {
    }
}

Current Player Counts

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "playerCount": 0,
  • "games": {
    }
}

Current Leaderboards

Authorizations:

Responses

Response samples

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

Punishment Statistics

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "watchdog_lastMinute": 0,
  • "staff_rollingDaily": 0,
  • "watchdog_total": 0,
  • "watchdog_rollingDaily": 0,
  • "staff_total": 0
}