Leaderboards

The leaderboard surface mirrors the game's true model: season → period → sheet (ladder) → content_type → class → entries. The bot discovers all of these from the live game — there is no static catalog to maintain.

Endpoints

GET /v2/leaderboards/seasons                                                      list active and historical seasons
GET /v2/leaderboards/seasons/{season}                                             season metadata (state, begin/end/wipe/reward, periods, sheets)
GET /v2/leaderboards/seasons/{season}/sheets                                      sheets (ladders) in a season
GET /v2/leaderboards/seasons/{season}/sheets/{sheet}                              sheet metadata
GET /v2/leaderboards/seasons/{season}/sheets/{sheet}/periods                      periods in a sheet
GET /v2/leaderboards/seasons/{season}/sheets/{sheet}/entries                      paginated ranked entries
GET /v2/leaderboards/seasons/{season}/sheets/{sheet}/characters/{name}/history    rank trajectory for a character

Query parameters

  • class — filter entries by character class (e.g. Fighter, Rogue)
  • period — period index, integer; defaults to the current period
  • page — 1-indexed, default 1
  • page_size — default 100, max 1000

Example

curl 'https://api.darkerdb.com/v2/leaderboards/seasons/EA7_HOF/sheets/TreasureCollector_Solo/entries?class=Fighter&period=0&page_size=5'


{
   "entries": [
      {
         "season_id":       "EA7_HOF",
         "sheet_id":        "TreasureCollector_Solo",
         "period_index":    0,
         "character_class": "Fighter",
         "character":       "ExamplePlayer",
         "rank":            1,
         "previous_rank":   2,
         "score":           "1450000",
         "karma":           42,
         "rank_tier":       "Diamond",
         "rank_tier_level": "I"
      }
   ],
   "page":      1,
   "page_size": 5,
   "total":     127
}

Legacy ID shim

Pre-v2 leaderboards used flat IDs like EA7_HOF_SHR_B. Those endpoints still respond:

GET /v2/leaderboards                  legacy summary, returns pointer + season list
GET /v2/leaderboards/{legacy_id}      legacy lookup, best-effort resolved to (season, sheet)

The legacy shim translates the prefix (e.g. EA7_HOF) to the new season key and returns the best-matching sheet's entries. It exists only to keep existing frontends rendering during their own migration — new integrations should target the structured /seasons/... paths above.