Skip to content
TopLordStats

Developers

TopLordStats read API

Pull your recorded alliance data and public kingdom rankings into spreadsheets, bots and dashboards.

OpenAPI JSON

Authentication and plans

API access requires Pro, Server Bundle or an active 7-day Pro trial. It follows the auto-sync entitlement. Small and lapsed workspaces receive a 403 error with a billing link. Owners and managers can create and revoke keys from API access in alliance settings or workspace settings.

New keys start with tl_live_ and contain 32 random base64url characters. Copy the full key when it is created; it is shown once. Send it in the Authorization header. Keep it on your server or in a private integration.

Authorization: Bearer tl_live_<your-key>

Alliance keys read only their alliance. Workspace keys read active alliances in that workspace (provide ?allianceId=<internal-id>) and its kingdom's public data. Kingdom endpoints reject alliance keys. Revoked, expired and out-of-scope keys fail immediately; keys also stop working if their creator loses manager access.

Every endpoint below is GET and read-only. IDs are internal TopLordStats IDs. The roster includes a game Lord ID only when available to managers in the signed-in app; public kingdom data never includes game IDs. Emails, website user links, notes, absences, aliases and private settings are omitted.

Data and periods

Power, kills, hero power, Castle level, VS and donations use decimal strings to preserve precision. Missing values stay null; zero is an observed zero. Readings carry their own ISO 8601 UTC observation date. Roles have a separate observation date.

History is newest first and accepts inclusive from and to dates or timestamps. A date-only boundary means UTC midnight; use a full end timestamp to include an entire final day. Metric history can be narrowed with memberId.

VS, donations and performance accept a Monday week=YYYY-MM-DD, defaulting to the current configured week. Responses return weekStart as UTC midnight plus the recorded reset hour. VS daily scores and the recorded weekly total are independent. Donation totals are reviewed weekly values, never live counters. Performance uses the app's evaluator and weighted standings; excused grades are shown as ungraded to keep absences private, and targets, weights and reasons are omitted.

Kingdom rankings are bounded captures, usually PARTIAL. A missing row does not mean zero or departure. Ranking metadata includes capture time, status, ranking limit and captured count. Public history is restricted to the latest 1,500 observations; meta.truncated reports that bound.

Ranking types: alliances — 1 kills, 2 power; Lords — 3 kills, 4 power, 5 Lord level, 13 hero power, 14 PvE stage, 15 highest hero power. Castle level is a roster reading and is separate from Lord level.

Errors

{
  "error": {
    "code": "AUTO_SYNC_REQUIRED",
    "message": "Public API access requires Pro, Server Bundle or an active Pro trial. Upgrade in Billing.",
    "details": {
      "billingUrl": "/billing?workspace=workspace_id"
    }
  }
}

Switch on error.code. 400: VALIDATION_ERROR (dates, week, cursor, limit or ranking). 401: UNAUTHENTICATED, INVALID_KEY, KEY_REVOKED, KEY_EXPIRED. 403: TENANT_MISMATCH, AUTO_SYNC_REQUIRED, TRIAL_EXPIRED. 404: MEMBER_NOT_FOUND, PLAYER_NOT_FOUND. 429: RATE_LIMITED. 500: INTERNAL_ERROR. Details are optional. Unsupported methods receive 405.

Alliance

GET /api/v1/alliance

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.toplordstats.com/api/v1/alliance?limit=100"
{
  "data": [
    {
      "id": "alliance_id",
      "name": "Alliance name",
      "tag": "TAG",
      "kingdom": 80
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Roster

GET /api/v1/alliance/lords

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.toplordstats.com/api/v1/alliance/lords?limit=100"
{
  "data": [
    {
      "id": "member_id",
      "name": "Lord name",
      "status": "ACTIVE",
      "gameLordId": null,
      "role": {
        "value": "R4",
        "observedAt": "2026-10-05T00:00:00.000Z",
        "source": "MANUAL"
      },
      "power": {
        "value": "126540800",
        "observedAt": "2026-10-05T00:00:00.000Z",
        "source": "MANUAL"
      },
      "kills": null,
      "heroPower": {
        "value": "48125300",
        "observedAt": "2026-10-05T00:00:00.000Z",
        "source": "MANUAL"
      },
      "castleLevel": {
        "value": "30",
        "observedAt": "2026-10-05T00:00:00.000Z",
        "source": "MANUAL"
      }
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Power history

GET /api/v1/alliance/lords/power

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.toplordstats.com/api/v1/alliance/lords/power?from=2026-10-01&to=2026-10-08&limit=100"
{
  "data": [
    {
      "memberId": "member_id",
      "name": "Lord name",
      "value": "126540800",
      "observedAt": "2026-10-05T00:00:00.000Z",
      "source": "MANUAL"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Kills history

GET /api/v1/alliance/lords/kills

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.toplordstats.com/api/v1/alliance/lords/kills?from=2026-10-01&to=2026-10-08&limit=100"
{
  "data": [
    {
      "memberId": "member_id",
      "name": "Lord name",
      "value": "843251",
      "observedAt": "2026-10-05T00:00:00.000Z",
      "source": "MANUAL"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Hero power history

GET /api/v1/alliance/lords/hero-power

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.toplordstats.com/api/v1/alliance/lords/hero-power?from=2026-10-01&to=2026-10-08&limit=100"
{
  "data": [
    {
      "memberId": "member_id",
      "name": "Lord name",
      "value": "48125300",
      "observedAt": "2026-10-05T00:00:00.000Z",
      "source": "MANUAL"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

VS

GET /api/v1/alliance/lords/vs

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.toplordstats.com/api/v1/alliance/lords/vs?week=2026-10-05&limit=100"
{
  "data": [
    {
      "memberId": "member_id",
      "name": "Lord name",
      "weekStart": "2026-10-05T00:00:00.000Z",
      "resetHour": 0,
      "day": 1,
      "score": null,
      "recordedAt": null,
      "weeklyTotal": "25000000",
      "weeklyRecordedAt": "2026-10-05T00:00:00.000Z"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Donations

GET /api/v1/alliance/lords/donations

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.toplordstats.com/api/v1/alliance/lords/donations?week=2026-10-05&limit=100"
{
  "data": [
    {
      "memberId": "member_id",
      "name": "Lord name",
      "weekStart": "2026-10-05T00:00:00.000Z",
      "resetHour": 0,
      "total": null,
      "recordedAt": null
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Performance

GET /api/v1/alliance/performance

Alliance key, or workspace key with ?allianceId=<internal-id>.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.toplordstats.com/api/v1/alliance/performance?week=2026-10-05&limit=100"
{
  "data": [
    {
      "id": "member_id",
      "name": "Lord name",
      "weekStart": "2026-10-05T00:00:00.000Z",
      "standing": null,
      "score": null,
      "vsDaily": {
        "value": null,
        "recorded": 0,
        "expected": 6,
        "complete": false,
        "grade": "ungraded"
      },
      "vsWeekly": {
        "value": null,
        "recorded": 0,
        "expected": 1,
        "complete": false,
        "grade": "ungraded"
      },
      "donations": {
        "value": null,
        "recorded": 0,
        "expected": 1,
        "complete": false,
        "grade": "ungraded"
      }
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Kingdom coverage

GET /api/v1/kingdom

Workspace key required. Uses public kingdom observations.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.toplordstats.com/api/v1/kingdom?limit=100"
{
  "data": [
    {
      "kingdom": 80,
      "ranking": 4,
      "kind": "LORD",
      "observedAt": "2026-10-05T00:00:00.000Z",
      "limit": 100,
      "status": "PARTIAL",
      "captured": 75
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Public Lords ranking

GET /api/v1/kingdom/lords

Workspace key required. Uses public kingdom observations.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.toplordstats.com/api/v1/kingdom/lords?ranking=4&limit=100"
{
  "data": [
    {
      "id": "public_entity_id",
      "name": "Lord name",
      "tag": "TAG",
      "value": "126540800",
      "position": 1,
      "observedAt": "2026-10-05T00:00:00.000Z"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Public alliances ranking

GET /api/v1/kingdom/alliances

Workspace key required. Uses public kingdom observations.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.toplordstats.com/api/v1/kingdom/alliances?ranking=2&limit=100"
{
  "data": [
    {
      "id": "public_entity_id",
      "name": "Alliance name",
      "tag": "TAG",
      "value": "8436250000",
      "position": 1,
      "observedAt": "2026-10-05T00:00:00.000Z"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Public Lord history

GET /api/v1/kingdom/lords/{lordId}/history

Workspace key required. Uses public kingdom observations. lordId is the internal ID returned by /kingdom/lords. metric defaults to power; also supports kills, hero-power, heroHighestPower, level and pveMaxStage.

curl -H "Authorization: Bearer $TOPLORDS_API_KEY" \
  "https://www.toplordstats.com/api/v1/kingdom/lords/public_lord_id/history?from=2026-10-01&to=2026-10-08&limit=100"
{
  "data": [
    {
      "lordId": "public_lord_id",
      "name": "Lord name",
      "metric": "power",
      "value": "126540800",
      "observedAt": "2026-10-05T00:00:00.000Z",
      "source": "OFFICIAL_LEADERBOARD"
    }
  ],
  "meta": {
    "limit": 100,
    "hasNextPage": false,
    "nextCursor": null
  }
}