Tier List API

A Minecraft player tier ranking and leaderboard system. Manage players, assign tiers across gamemodes, and query leaderboards.

General

Base URL

http://localhost:7070 — this page is served at /

Format

JSON request & response bodies

Authentication

Bearer token via Authorization header. Required on all write endpoints.

Rate Limiting

None currently enforced.

Valid Regions

EU NA AS SA AF ME

Tier System

Tiers range from 5 (lowest) to 1 (highest). Each tier has positions. Tiers 1-2 may also be marked as retired.

TierPositionsRetired Variant
5LOW, MID, HIGHNo
4LOW, MID, HIGHNo
3LOW, HIGHNo
2LOW, HIGHYes
1LOW, HIGHYes

Endpoints

POST /api/players Auth Required

Register a new player. The Minecraft UUID is validated against Mojang's API.

Request Body
{
  "minecraftUUID": "550e8400-e29b-41d4-a716-446655440000",
  "region": "EU"
}
201 Created 400 Invalid UUID/Region 409 Already Exists
GET /api/players/{uuid} Public

Get full player info including all gamemode profiles and leaderboard ranks.

Response
{
  "minecraftUUID": "550e8400-...",
  "region": "EU",
  "createdAt": "2026-01-15T12:00:00Z",
  "gamemodeProfiles": [
    {
      "gamemode": { "id": 1, "name": "SG", "isActive": true },
      "currentTier": { "id": 3, "tierNumber": 4, "tierPosition": "HIGH", "retired": false, "sortOrder": 4 },
      "peakTier": { "id": 1, "tierNumber": 3, "tierPosition": "LOW", "retired": false, "sortOrder": 5 },
      "leaderboardRank": 12
    }
  ],
  "globalLeaderboardRank": 5,
  "result": "SUCCESS"
}
200 OK 404 Not Found
PATCH /api/players/{uuid} Auth Required

Update a player's Minecraft UUID or region.

Request Body
{
  "newMinecraftUUID": "660e8400-e29b-41d4-a716-446655440000",
  "newRegion": "NA"
}
200 OK 400 Invalid UUID/Region 404 Not Found
GET /api/players/{uuid}/profiles/ Public

Get all gamemode profiles for a player.

Response
{
  "profiles": [
    {
      "gamemode": { "id": 1, "name": "SG", "isActive": true },
      "currentTier": { "id": 3, "tierNumber": 4, "tierPosition": "HIGH", "retired": false, "sortOrder": 4 },
      "peakTier": { ... },
      "leaderboardRank": 12
    }
  ],
  "globalLeaderboardRank": 5,
  "result": "SUCCESS"
}
200 OK 404 Not Found
POST /api/players/{uuid}/profiles/{gamemode}/assignments Auth Required

Assign or update a player's tier in a specific gamemode. Automatically updates leaderboards.

Request Body
{
  "tierLevel": 3,
  "position": "HIGH",
  "retired": false
}
200 OK 400 Invalid Tier/Gamemode 404 Player Not Found 500 Database Error
GET /api/leaderboard/{gamemode} Public

Get the leaderboard for a specific gamemode. Optional ?limit=N query param (default 50).

Response
[
  {
    "rank": 1,
    "minecraftUuid": "550e8400-...",
    "sortOrder": 12
  }
]
200 OK 404 No Data
GET /api/leaderboard/global Public

Get the global leaderboard (aggregated across all gamemodes). Optional ?limit=N query param (default 50).

Response
[
  {
    "rank": 1,
    "minecraftUuid": "550e8400-...",
    "totalSortOrder": 38
  }
]
200 OK 404 No Data
POST /api/gamemodes Auth Required

Register a new gamemode.

Request Body
{
  "gamemodeName": "SG",
  "isActive": true
}
201 Created 409 Already Exists

Authentication Example

curl -X POST http://localhost:7070/api/players \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"minecraftUUID": "550e8400-e29b-41d4-a716-446655440000", "region": "EU"}'

Unauthorized requests return 401.