Developer API · v1
Base URL: /api/v1
HTTP Header
X-API-Key: mctl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
| Header | |
|---|---|
X-RateLimit-Limit | |
X-RateLimit-Remaining | |
X-RateLimit-Reset |
GET/api/v1/stats
Response
{ "players": 128, "tier1": 6, "tier2": 14, "regions": 1, "modes": 1, "tests": 342 }GET/api/v1/modes
| Tier | Tier | ||
|---|---|---|---|
| HT1 | 60 | LT1 | 45 |
| HT2 | 30 | LT2 | 20 |
| HT3 | 10 | LT3 | 6 |
| HT4 | 4 | LT4 | 3 |
| HT5 | 2 | LT5 | 1 |
GET/api/v1/rankings/vanilla
limit | |
offset | |
region | |
tier | |
search |
Response
{
"mode": "vanilla",
"total": 1, "limit": 50, "offset": 0,
"players": [
{
"rank": 1,
"name": "Steve",
"uuid": "8667ba71-b85a-4004-af54-457a9734eed7",
"region": "TW",
"points": 60,
"title": "Combat Specialist",
"badges": ["booster"],
"tiers": { "vanilla": { "tier": "HT1", "points": 60, "retired": false } },
"stats": { "wins": 12, "losses": 4 },
"updatedAt": "2026-09-25T08:00:00.000Z"
}
]
}GET/api/v1/players
GET/api/v1/players/{name | uuid}
GET/api/v1/bans
GET/api/v1/bans/{name | uuid}
Response
{
"banned": true,
"ban": {
"name": "Hacker1",
"uuid": null,
"reason": "KillAura",
"bannedAt": "2026-09-25T15:00:00.000Z",
"expiresAt": null
}
}| error | ||
|---|---|---|
| 401 | missing_api_key | |
| 401 | invalid_api_key | |
| 400 | invalid_region | |
| 404 | player_not_found | |
| 429 | rate_limited |
cURL
bash
curl -H "X-API-Key: YOUR_KEY" \ "/api/v1/rankings/vanilla?limit=10"
JavaScript (Node.js / Discord Bot)
javascript
const res = await fetch('/api/v1/players/Steve', { headers: { 'X-API-Key': process.env.MCTL_API_KEY }, }); const player = await res.json(); console.log(player.name, player.tiers.vanilla.tier); // Steve HT1
Python
python
import os, requests r = requests.get( "/api/v1/rankings/vanilla", headers={"X-API-Key": os.environ["MCTL_API_KEY"]}, params={"region": "TW", "limit": 10}, ) for p in r.json()["players"]: print(p["rank"], p["name"], p["tiers"]["vanilla"]["tier"])