API

REST API

Public endpoints for player profiles, Minecraft skins and renders, rankings, clans, events and server data. No authentication required for the endpoints below.

Base URLhttps://api.elotiers.com/v1

Minecraft Profile & Skin APIs

Public, no API key required, CORS-enabled

GET/api/minecraft/profile?q={name_or_uuid}

Resolve a Minecraft username or UUID to get UUID, name, skin, cape, textures, and render URLs.

Parameter	Type	Description
`q`required	string	Minecraft username or UUID
`refresh`	bool	Force cache refresh

GET/api/minecraft/uuid/{name}

Lookup UUID by Minecraft username.

GET/api/minecraft/name/{uuid}

Lookup current Minecraft name by UUID.

GET/api/minecraft/skin/{id}

Get skin/cape data by UUID, name, or texture ID.

Render URLs

Path	Description
`/avatar/{uuid}[/{size}].png`	2D avatar (face crop)
`/render/head/{uuid}?width=180&height=180`	Head render
`/render/bust/{uuid}?width=240&height=280`	Bust/upper body render
`/render/full/{uuid}?width=280&height=380`	Full body render
`/3d/head/{uuid}?width=180&height=180`	3D head render
`/2d/head/{uuid}?width=180&height=180`	2D head render
`/skin/{uuid}.png`	Raw skin texture PNG
`/cape/{uuid}.png`	Raw cape texture PNG

Render Options

Option	Description
`refresh / fresh`	Force re-fetch from Mojang
`helm`	Show/hide helmet overlay (default: true)
`overlay`	Show/hide skin overlay layer (default: true)
`shadow`	Show/hide drop shadow (default: true)
`width / height`	Output size in pixels (8–1024)

Response Example

// GET /api/minecraft/profile?q=Steve
{
  "success": true,
  "uuid": "069a79f4-44e9-4726-a16f-93fa8e7aa90f",
  "name": "Notch",
  "skin": {
    "url": "http://textures.minecraft.net/texture/abc123",
    "model": "classic",
    "texture_id": "abc123",
    "download": "/skin/069a79f4-.../120.png"
  },
  "cape": null,
  "renders": {
    "avatar": "/avatar/069a79f4-.../120.png",
    "head": "/render/head/069a79f4-...?width=180&height=180",
    "bust": "/render/bust/069a79f4-...?width=240&height=280",
    "full": "/render/full/069a79f4-...?width=280&height=380",
    "skin": "/skin/069a79f4-....png",
    "cape": "/cape/069a79f4-....png"
  }
}

Rankings & Leaderboard

Rate-limited: 120 requests per 60 seconds per IP

GET/api/top?type={source}&mode={mode}&page={page}&limit={limit}

Top players leaderboard by tier source and game mode.

Parameter	Type	Description
`type`	string	Tier source: mctiers, pvptiers, subtiers, flowpvp, custom (default: mctiers)
`mode`	string	Game mode filter (e.g. overall, sword, pot, uhc)
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page, max 100 (default: 25)

GET/api/rankings/unified?mode={mode}&page={page}&limit={limit}

Unified aggregated rankings across all tier sources with visible Elo.

Parameter	Type	Description
`mode`required	string	Game mode (e.g. overall, sword, pot, uhc)
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page, max 100 (default: 25)

GET/api/players/compare?players={uuid1},{uuid2}

Compare multiple players' tier rankings and custom stats. Max 5 UUIDs.

Parameter	Type	Description
`players`required	string	Comma-separated UUIDs (max 5)

Player Profile & Stats

Public, no API key required

GET/api/profile?q={name_or_uuid}

Full player profile with all tier rankings, stats, clan info, and social data.

Parameter	Type	Description
`q`required	string	Minecraft username or UUID
`refresh`	bool	Force cache refresh from tier sources

GET/api/stats/player?q={name_or_uuid}

Raw custom stats submitted by server plugins (wins, losses, kill/death ratios).

Parameter	Type	Description
`q`required	string	Minecraft username or UUID

GET/api/stats

Global platform statistics: total players, matches played, online servers, active game modes.

Clans

Public, no API key required

GET/api/clans/top?mode={mode}&page={page}&limit={limit}

Clan leaderboard aggregated by member visible Elo.

Parameter	Type	Description
`mode`	string	Game mode filter (default: overall)
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page, max 100 (default: 25)

GET/api/clans/{tag}

Public clan info by clan tag including members, stats, and relations.

Events

Public, no API key required

GET/api/events?status={status}&server_id={id}

List events with optional filters for status and server.

Parameter	Type	Description
`status`	string	Filter by status: scheduled, live, ended, cancelled
`server_id`	string	Filter by server ID
`from`	string	Start date filter (ISO 8601)
`to`	string	End date filter (ISO 8601)

GET/api/events/active

Live and upcoming events scheduled within the next 24 hours.

Search & Social

Public, no API key required

GET/api/search/autocomplete?q={query}

Player name autocomplete suggestions. Minimum 2 characters.

Parameter	Type	Description
`q`required	string	Search query (min 2 characters)

GET/api/random-name

Get a random cached player name and UUID.

GET/api/social/summary?uuids={uuid1},{uuid2}

Public social summary for given UUIDs: clan membership, relation status.

Parameter	Type	Description
`uuids`required	string	Comma-separated list of UUIDs
`self_uuid`	string	Include relation info relative to this UUID

Rate Limits

Public Endpoints

requests per minute

Rankings & Leaderboard

120

requests per 60s per IP

Authenticated

300

requests per minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

Authentication

All endpoints on this page are public and do not require authentication. For authenticated requests (account management, developer keys, admin endpoints), include your API key in the header:

Authorization: Bearer YOUR_API_KEY

To get an API key, sign in with Discord and visit your developer dashboard.

Error Codes

Code	Meaning
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Player or resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Try again later