EaglerTiers REST API Overview

Welcome to the official EaglerTiers REST API documentation. The API allows developers to programmatically access public player rankings, profile details, gamemode tier lists, and search functionality.

All responses are formatted in JSON with standard HTTP status codes.

Authentication

All read operations (GET requests) are publicly accessible and do not require an API key.

Write operations (POST, PUT, DELETE) are protected and require an authorized API key. You can pass your key using either an HTTP header or directly in the URL query string:

X-API-Key: your_api_key_here

curl -X POST "https://api.eaglertiers.com/api/player?key=your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"username":"NewPlayer","region":"NA"}'

Rate Limits

To ensure fair usage and service reliability for all users, requests are rate-limited per client IP:

• Public Requests: 120 requests per minute
• Response on Exceeded Limit: 429 Too Many Requests

Tiers, Retired Tiers & Peak Tiers

The EaglerTiers ranking system tracks three tier categories for each gamemode:

• Active Tiers (tiers): Currently active gamemode ranks. Awards 100% of the tier's point value.
• Retired Tiers (retiredTiers): Inactive or retired ranks. Awards 50% of the active tier's point value.
• Peak Tiers (peakTiers): All-time highest rank achieved by the player in that gamemode. Displays historical achievement on profiles (0 points added to active standings).

* Note: Overall points = Sum of Active Points + (0.5 × Sum of Retired Points). Peak tiers record historical bests.

Fetch Paginated Rankings

Returns a paginated list of ranked players sorted by total points in descending order.

curl -s "https://api.eaglertiers.com/api/players?page=1&key=YOUR_API_KEY"

{
  "data": [
    {
      "id": 1,
      "username": "EaglerGod",
      "region": "NA",
      "avatarUrl": "https://render.crafty.gg/3d/bust/EaglerGod",
      "createdAt": "2026-04-20T12:00:00.000Z",
      "tiers": {
        "vanilla": "HT1",
        "sword": "LT1",
        "mace": null
      },
      "retiredTiers": {
        "axe": "HT2"
      },
      "peakTiers": {
        "vanilla": "HT1",
        "sword": "LT1",
        "axe": "HT2",
        "mace": "LT3"
      },
      "totalPoints": 120,
      "position": 1
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 142,
    "totalPages": 8
  }
}

Fetch All Players

Returns an unpaginated array of all ranked players in the system.

const response = await fetch('https://api.eaglertiers.com/api/players/all');
const { data } = await response.json();
console.log(`Total players: ${data.length}`);

Get Player Profile

Returns full details, rank tiers, position, and total points for a specific player by username.

import requests

res = requests.get('https://api.eaglertiers.com/api/players/EaglerGod')
player = res.json()
print(f"Rank: #{player['position']} | Points: {player['totalPoints']}")

Get Gamemode Tier List

Returns players ranked within a specific gamemode tier list.

Supported Gamemodes:

overall, vanilla, mace, axe, sword, smp, diamondsmp, uhc, pot, nethop, cart

curl -s "https://api.eaglertiers.com/api/rankings/sword?page=1&key=YOUR_API_KEY"

Search Players

Search for players by partial or full username match (up to 10 results returned).

curl -s https://api.eaglertiers.com/api/search?q=eagler