tier list api
get your players, tiers and test results onto your own website. there's no api key and nothing to sign up for, you just fetch a url.
1. your api url
your bot comes with its own api url. paste it below and every example on this page switches to it. if you don't know it, ask us in your ticket.
2. try it
pick one, hit send, see what comes back. this is a real request to your bot.
nothing sent yet
the answer shows up here
3. use it on your site
that request you just made, in code. the path comes from the box above, so change it there.
the browser is allowed to call the api from any website (cors is on), so the javascript version works on a plain html page.
here's a small leaderboard. the code is under it and it's running live right now:
routes
all of them are GET and all of them answer in json. hit "use" to drop one in the box up top, then change the placeholders (UUID, NAME...).
| path | what you get | |
|---|---|---|
/mode/list | the gamemodes of your tier list | |
/mode/overall?count=10 | everyone sorted by points | |
/mode/vanilla?count=10 | players of a gamemode, split by tier (1 to 5) | |
/mode/vanilla/retired?count=10 | same thing but only retired players | |
/profile/by-name/NAME | a player's profile from their minecraft name | |
/profile/UUID | a player's profile from their uuid | |
/profile/UUID/rankings | just the rankings of that player | |
/profile/by-discord/ID | a player's profile from their discord id | |
/tests/recent?count=10 | the latest finished tests | |
/tests/recent/high?count=10 | latest tests that ended in tier 1 or 2 | |
/tests/UUID?count=10 | tests done by one tester |
count is needed on the list routes (max 50, and max 20 for /tests/recent). from skips that many results if you want pages. on profile routes you can add ?tests and ?badges to get those too.
want every field explained? the full reference is here.
how tiers work
tier goes from 1 (best) to 5. pos says if it's the high or the low version of that tier:
| pos | means |
|---|---|
0 | high (HT) |
1 | low (LT) |
so {"tier": 3, "pos": 1} is LT3 and {"tier": 1, "pos": 0} is HT1. points are set in your bot's settings and show up as points. retired: true means the player stopped playing, so show their peak tier instead of the current one.
when something goes wrong
| status | what happened |
|---|---|
400 | bad or missing parameter, the message field tells you which one. error.invalid_gamemode means the gamemode doesn't exist. |
404 | that player isn't on the list. no json in this one. |
429 | too many requests from one ip. wait the number of seconds in the Retry-After header. |
500 | something broke on our side. try again in a minute, then tell us. |
errors look like {"code": "error.bad_request", "message": "missing query parameter `count`"}
good to know
- data updates every few seconds, so don't expect results to change instantly after a test.
- the limit is 120 requests per minute for each visitor. cache what you can on your side.
- test history only starts from the day the api was added to your bot. older tests aren't in there.
- only players who linked their minecraft account in the bot show up.
- for skins you can use
https://mc-heads.net/avatar/UUID/64(that's what the leaderboard above does).