A simple to use, stateless API facade for communicating with the Hypixel API,
built to make it easier to get the information that matters.
The API will automatically calculate skill, slayer, catacomb, and dungeon classes levels for you so you don't have to, making it quick and easy to get started.
Easily find how much money a player has sent on slayers, or how fast their latest dungeon run was, or even what their best scores is in human readable formats.
Get the weight of player profiles, and the weight of individual skills, slayer types, dungeon classes and catacombs for an quick and easy way to see a profiles progress into the game.
Authentication
Authentication & Hypixel Tokens
The Facade API uses Hypixel API keys to authenticate
requests. You can get your own API key by logging into mc.hypixel.net with a Minecraft
account and running /api new to generate a new API
token.
Once you have your own token you can authenticate with the API in two different ways.
You can either use the Hypixel API key query paramater, this is the exact same way you authenticate with
the actual Hypixel API, to use this
method you should add a ?key=your-token-here query
paramater to the end of API requests.
You can also use an authorization header instead, to use this method you should add a
Authorization header to your API requests, where
the value of the header is your API
token.
Responses
API responses and what to look for
All endpoints in the API returns all their responses in JSON, all requests will return a
status key which should match the response status
code that was returned, it will also
return a data key for successful responses, and a
reason key for failed requests.
API response codes
| Status Code | Reason |
|---|---|
| 200 | Successful request, this will return the data for the profile that were requested. |
| 400 |
The request is missing an authentication method, you must either provide a valid
key query paramater, or an
Authentication header.
|
| 403 | The provided Hypixel API token is invalid, or does not exists. |
| 404 | There is either no player with the given UUID, or the player has no SkyBlock profiles. |
| 429 |
The Hypixel API rate-limited was reached, if you see this in your resposnes you should slow down
requests, or start caching response to
prevent having to make as many requests in the future.
The API will return RateLimit-Remaining
and
RateLimit-Reset headers with every request
that you can use to see how many requests
you have left for the current minute.
|
| 500 |
An internal error occurred in the API, or the Hypixel API responded with an unknown error code.
If this error code is returned, you may also see a stack JSON key which tells
you where in the code it broke, please report these errors back on
GitHub as an issue so they
can be fixed.
|
| 502 | Hypixels API is experiencing some technical issues and may not be available, if you get this error code just re-send your request at a later time, hopefully Hypixels API will work again by then. |
| 503 | Hypixels API is in maintenance mode, you can't really do much about this, just try re-send your request when the API is back online. |
API Endpoints
URLs and how to use the API
A simple pingable endpoint to check if the API is online and is working, will respond with "Hello, World".
Example
curl -X GET 'https://hypixel-api.senither.com/v1/hello' \
-H 'Authorization: your-hypixel-api-token'
Get some stats about the API, like the current uptime both in seconds and as a human readable string, and how many requests the API have handled in the last minute, hour, and since it was last restarted.
Example
curl -X GET 'https://hypixel-api.senither.com/v1/stats' \
-H 'Authorization: your-hypixel-api-token'
Gets every profile a user has as a list, where each profile have had its levels and stats calculated.
Example
curl -X GET 'https://hypixel-api.senither.com/v1/profiles/18e174ef-078f-4275-8dcd-51d495d1096b' \
-H 'Authorization: your-hypixel-api-token'
You can view an example of the response on GitHub: gist.github.com/Senither/44834843a6f79e00daf6d327d791352f
Paramaters
| Paramater | Description |
|---|---|
| UUID | This is the UUID of the player that the profiles should be loaded for. |
Gets a single profile for the player with the given UUID, the given strategy is what selects the players profile.
Example
curl -X GET 'https://hypixel-api.senither.com/v1/profiles/18e174ef-078f-4275-8dcd-51d495d1096b/weight' \
-H 'Authorization: your-hypixel-api-token'
You can view an example of the response on GitHub: gist.github.com/Senither/04cd54e8f08d77d665d29515e0d8ffbc
Paramaters
| Paramater | Description |
|---|---|
| UUID | This is the UUID of the player that the profile should be loaded for. |
| Strategy | The strategy that should be used to select the profile, you can see the list of available strategies below. |
Strategies
How to select SkyBlock profiles effectively.
The strategies are keys that can be given to the API to tell it how to select a profile, if no strategy is given all profiles for a player will be returned as a list instead.
List of strategies
| Name | Keys | Description |
|---|---|---|
| Last Save At | last_save_at last_saved last_save latest saved save | Selects the profile that was last used by the player. |
| Weight | weights weight we | Selects the profile with the highest weight. |
| Skills | skills skill | Selects the profile with the highest skill average. |
| Slayers XP | slayers slayer | Selects the profile with the highest total slayer XP. |
| Catacombs | catacombs catacomb dungeons dungeon cata | Selects the profile with the highest catacomb level. |
If no valid strategy key is given the API will assume the given strategy is the name of the profile that should be selected.