Tracker API

If you run a Rise of Kingdoms site and want to show a player’s speedup and material totals on their profile, this endpoint hands you the numbers Codex Helper already read from their screenshots.

It is not open. You need a key, and keys are issued by hand. Ask on the support server with what you are building and roughly how many requests a day you expect.

The request

GET https://codexhelper.com/api/partner/tracker/<discord_user_id>
Authorization: Bearer <your key>

The id is a Discord user id, the same 17-to-20 digit number Discord shows when you copy a user id. Nothing else identifies a player: link accounts with Discord OAuth on your side so the id you send is one your visitor proved they own.

The response

{
  "user_id": "285201373266575361",
  "speedups": {
    "building": 12450,
    "research": 8300,
    "training": 4100,
    "healing": 2250,
    "universal": 96000,
    "unit": "minutes",
    "scanned_at": 1757000000
  },
  "materials": {
    "counts": {
      "ore_common": 700,
      "ore_advanced": 107,
      "bone_epic": 13,
      "chest_legendary": 2
    },
    "scanned_at": 1757000100
  }
}

Speedups are minutes, matching how the game shows them. A type is null when the member’s latest screenshot did not show it, which is not the same as holding none of it. Speedup rows only hold what the newest scan read; older scans are not carried forward.

Material keys are <material>_<rarity>. Materials are ore, leather, ebony, bone, chest (Choice Chest) and randomchest. Rarities are common, advanced, elite, epic and legendary. A key that is absent means no scan has ever read that tile. Do not read a missing key as a zero; a real zero is sent as 0.

scanned_at is a Unix timestamp in seconds. Each tracker carries its own, because a member can scan one without the other.

Either speedups or materials can be null on its own, for a member who has only ever used one tracker.

What you will not get

404 with {"error": "No tracked data for this member"} means the member has never scanned anything, or does not use Codex Helper. You cannot tell those two apart.

Plenty of players have never used the tracker, so build your profile page with a missing panel as a normal case rather than an error state.

Whether a member has their cards posted publicly or sent to their DMs makes no difference here. That setting controls where their card appears in Discord, nothing more.

Limits and caching

Responses carry Cache-Control: public, max-age=300. Respect it. Members are capped at 4 material scans and 6 speedup scans a day, so a five-minute-old answer is never meaningfully out of date, and re-fetching faster only spends your quota.

Keys have a daily request ceiling. Over it, you get 429 with a Retry-After header. If your traffic is growing, ask for a higher ceiling before you start hitting it rather than after.

Errors

Code	Meaning
400	The user id is not a valid Discord snowflake
401	Missing, malformed, unknown, or revoked key
404	That member has never scanned anything
429	Daily request ceiling reached

A 401 is deliberately identical whatever the reason, so the endpoint cannot be used to work out whether a key is real.

Keeping your key

The key is a password. It goes in an environment variable on your server, never in browser code, a public repo, or a support ticket. Nobody can look it up for you: only a hash of it is stored, so a lost key is replaced, never recovered. If it leaks, say so and it will be revoked the same day.