MC Leaderboards API Documentation

Complete API reference for the MC Leaderboards platform

Base URL: https://mcleaderboards.org/api
Security Notice:

📊 Player Endpoints

GET /api/players

Get all players and their ratings across all gamemodes.

Response:

{
  "player-id": {
    "name": "PlayerName",
    "username": "minecraft_username",
    "region": "US",
    "glickoRatings": {
      "overall": { "rating": 1650, "rd": 150, "volatility": 0.06, "gamesPlayed": 15 },
      "vanilla": { "rating": 1700, "rd": 120, "volatility": 0.05, "gamesPlayed": 10 }
    },
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-15T00:00:00Z"
  }
}
POST /api/players 🔒 Admin/Tier Tester

Add a new player to the leaderboards.

Request Body:

name (string, required) - Player display name
region (string, optional) - Player region

🔐 Authentication Endpoints

POST /api/auth/microsoft 🔒 Auth Required

Verify Microsoft account and link Minecraft username.

Important: This endpoint requires a valid Microsoft OAuth access token. Users must authenticate through Microsoft's OAuth flow first.

Request Body:

accessToken (string, required) - Microsoft OAuth access token

Response:

{
  "success": true,
  "minecraftUsername": "Steve",
  "minecraftUUID": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "message": "Minecraft account verified successfully"
}
POST /api/auth/microsoft/disconnect 🔒 Auth Required

Disconnect linked Minecraft account.

🎮 Queue & Matchmaking

POST /api/queue/join 🔒 Auth Required Microsoft Required

Join the tier test queue for a specific gamemode.

Security Requirements:
  • ✅ Must have verified Minecraft account via Microsoft
  • ✅ Account must not be blacklisted
  • ✅ Valid Firebase authentication

Request Body:

gamemode (string, required) - One of: vanilla, uhc, pot, nethop, smp, sword, axe, mace

Response:

{
  "success": true,
  "queueId": "queue-entry-id",
  "message": "Joined vanilla queue"
}

Error Responses:

// Not verified
{
  "error": "Minecraft account verification required",
  "message": "You must connect and verify your Minecraft account before joining the queue"
}

// Blacklisted
{
  "error": "Account blacklisted",
  "message": "Your account has been blacklisted and cannot join the queue",
  "reason": "Cheating",
  "blacklistedAt": "2025-01-01T00:00:00Z"
}
POST /api/queue/leave 🔒 Auth Required

Leave the current queue.

GET /api/queue/status 🔒 Auth Required

Get your current queue status.

GET /api/queue/stats

Get public queue statistics.

🎯 Tier Tester Endpoints

GET /api/tier-testers

Get list of all tier testers and their status.

POST /api/tier-tester/availability 🔒 Tier Tester

Set tier tester availability status.

Request Body:

available (boolean, required) - Availability status
gamemodes (array, optional) - Available gamemodes

⚠️ Blacklist Management

GET /api/blacklist/check/:username

Check if a player is blacklisted.

POST /api/blacklist 🔒 Admin

Add a player to the blacklist.

DELETE /api/blacklist/:blacklistId 🔒 Admin

Remove a player from the blacklist.

📋 Application Endpoints

GET /api/applications 🔒 Auth Required

Get tier test applications (admins see all, users see their own).

POST /api/applications 🔒 Auth Required

Submit a new tier test application.

🛡️ Rate Limits

Rate Limit Details:

🔒 Security Features

Important Notes: