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 & 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
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
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
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
data key for successful responses, and a
reason key for failed requests.
API response codes
|200||Successful request, this will return the data for the profile that were requested.|
The request is missing an authentication method, you must either provide a valid
|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.|
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
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
|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.|
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".
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.
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.
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
|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.
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
|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.|
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
|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.