PUBLIC JSON API · VERSION 2

API Reference

Read-only Vanilla tier and player data for websites, bots, plugins, and integrations.

Base URL

/api/v2

GET onlyRead-onlyJSONNo API key currently required

This deployment runs one Discord Guild and one active gamemode: Vanilla. The MCRanks API v2 routes remain available.

Available gamemode

vanilla — Vanilla

Endpoints

GET/health

Check API availability and service identity.

GET/modes

List available ranking views. Vanilla is the only gamemode; Overall remains for compatibility.

GET/rankings/vanilla

Vanilla tierboard grouped into tier1–tier5 and HT/LT buckets.

GET/rankings/overall?limit=50&offset=0

Compatibility ranking summary based on the active Vanilla points. Limit is 1–100.

GET/players/{username}

Player profile by Minecraft username.

GET/players/uuid/{uuid}

Player profile by UUID, dashed or undashed.

GET/players?search=Example

Search up to 10 matching usernames.

Tierboard response

{
  "data": {
    "mode": {"key":"vanilla","name":"Vanilla"},
    "tiers": {
      "tier1": {"ht": [], "lt": []},
      "tier2": {"ht": [], "lt": []},
      "tier3": {"ht": [], "lt": []},
      "tier4": {"ht": [], "lt": []},
      "tier5": {"ht": [], "lt": []}
    }
  }
}

Each player object contains username, UUID, region, and current/peak/previous tier metadata.

Player profile example

{
  "data": {
    "username": "ExamplePlayer",
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "location": "ASIA",
    "points": {"overall": 60, "vanilla": 60},
    "modes": {
      "vanilla": {
        "current": {"tier":"HT1","level":1,"kind":"HT","points":60,"label":"High Tier 1"},
        "peak": {"tier":"HT1","level":1,"kind":"HT","points":60,"label":"High Tier 1"},
        "previous": {"tier":"LT1","level":1,"kind":"LT","points":45,"label":"Low Tier 1"},
        "points": 60
      }
    }
  }
}

Examples

curl -sS 'https://YOUR-DOMAIN/api/v2/rankings/vanilla'
curl -sS 'https://YOUR-DOMAIN/api/v2/players/ExamplePlayer'
curl -sS 'https://YOUR-DOMAIN/api/v2/players/uuid/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Full specification: OpenAPI 3.0 JSON. Detailed source notes are in API.md.

Region values

The location property uses canonical stored region names: NORTH_AMERICA, EUROPE, ASIA, AUSTRALIA, and SOUTH_AMERICA. Display abbreviations may be NA, EU, AS, AU, and SA.