CODEBREAKERS stats

Public API reference

Read-only HTTP access to every statistic the CodeBreakers tournament bot has recorded: players, squads, matches, maps, classes and tournaments, as totals or sliced any way you like. Requires an API key.

Contents

• Getting started
• Authentication
• Scopes
• Rate limits
• Errors
• Conventions
• Identifiers
• The stats engine
• Endpoint reference
• Field glossary
• How the numbers are derived
• Data caveats
• Examples

Getting started

The API is versioned and lives under /v1:

https://api.stats.playrservers.com/v1

Every request needs a key. Ask a CodeBreakers organiser for one; keys are issued per consumer, so please do not share yours - usage is attributed to it, and a key seen coming from several places gets flagged as leaked.

curl -H "Authorization: Bearer cbk_YOUR_KEY" \
  https://api.stats.playrservers.com/v1/status

GET /v1 returns a machine-readable index of every endpoint, so you can discover the surface without this page.

Authentication

Send your key in a header. Either of these works:

Authorization: Bearer cbk_YOUR_KEY
X-API-Key: cbk_YOUR_KEY

Keys are stored as a SHA-256 hash. Nobody, including the CodeBreakers organisers, can read your key back out after it is issued. If you lose it, ask for it to be revoked and reissued.

A key may optionally be locked to one or more IP addresses or CIDR ranges. If yours is, a request from anywhere else fails with 403 ip_not_allowed - the whole request, not a reduced version of it. Ask for a lock if your integration runs from a fixed address; it is the single most effective protection against a leaked key being useful to anyone else.

Scopes

Without the identity scope those fields are returned as the literal string "restricted". That is deliberately not null: null is a real answer meaning "no Discord identity has ever been recorded for this player", and you need to be able to tell the two apart.

// key WITHOUT the identity scope
{ "embark_id": "SHADOW#7360", "discord_username": "restricted" }

// key WITH the identity scope
{ "embark_id": "SHADOW#7360", "discord_username": "shadow" }

GET /v1/status tells you which scopes your own key carries.

Rate limits

Keys default to 120 requests per minute; yours may have been issued with a different budget. Every successful response carries the current state of your budget:

The window is a fixed minute, not a rolling one. If you are pulling a lot of data, prefer one request with a large limit over many small ones, and use /v1/stats rather than fetching each player individually.

Responses are sent with Cache-Control: private, no-store because the body depends on your key. Cache them yourself if you need to; the underlying data only changes when a tournament match is recorded, so caching for a minute or two costs you nothing.

Errors

Errors are JSON, with a stable machine-readable error code and a human message. Branch on error, never on message - the wording may be improved at any time.

{
  "ok": false,
  "error": "key_required",
  "message": "this API requires a key. Send it as `Authorization: Bearer cbk_...` ..."
}

Conventions

Timestamps

Every time value (played_at, first_seen_at, edited_at, ...) is a Unix timestamp in milliseconds, UTC. In JavaScript: new Date(played_at). In Python: datetime.fromtimestamp(played_at / 1000, tz=timezone.utc).

Pagination

List endpoints accept limit and offset, and report the unpaginated total alongside the rows. limit is capped at 500.

GET /v1/players?limit=100&offset=200
{ "ok": true, "total": 138, "limit": 100, "offset": 200, "players": [ ... ] }

Filters

These apply to /v1/stats, /v1/stats.csv, /v1/players and /v1/teams, and can be combined freely.

Sorting

sort takes any of the keys below, and dir takes asc or desc (default desc). An unrecognised key is an error, not a silent fallback.

matches  eliminations  assists  deaths  revives  combat  support  objective
wins  avg_placement  kd  label
elims_per_match  assists_per_match  deaths_per_match  revives_per_match
combat_per_match  support_per_match  objective_per_match

Identifiers

A player can be addressed three ways, and all three return the same record:

GET /v1/players/SHADOW%237360     # Embark ID, "#" percent-encoded as %23
GET /v1/players/SHADOW-7360       # "-" in place of "#", friendlier in a path
GET /v1/players/71                # numeric id

The #tag is part of the identity: SHADOW#7360 and SHADOW#1111 are two different people and are never merged. If you pass a bare name with no tag it resolves only when exactly one player matches; otherwise you get 404 not_found.

Teams and matches are addressed by numeric id, but a match also has a stable bracket identifier - its tournament code plus its pod id:

GET /v1/matches/318                              # numeric id
GET /v1/tournaments/CB-42WA/matches/groups-0     # bracket identifier

Team names are only unique within a tournament, and squads change names between events. Every team object carries its tournament_code so you can re-resolve one later.

The stats engine

GET /v1/stats is the endpoint behind "any stat, sliced any way". It groups the entire corpus by one dimension, applies your filters, and returns summed totals plus every rate derived from them.

GET /v1/stats?group_by=player&tournament=CB-42WA&sort=kd&min_matches=5&limit=25

Every row also carries the generic pair key and label, which hold the same values. /v1/stats.csv returns the identical rows as CSV, for a spreadsheet.

Endpoint reference

Meta

Aggregates

Tournaments

Players

Teams

Matches

Reference lists

Field glossary

Per-player, per-match

Per-squad, per-match

Per-match

Derived on aggregates

How the numbers are derived

No ratio is ever stored. The database holds sums only; K/D, per-match averages and win rates are computed at query time. That is why a moderator correcting one mis-read elimination instantly fixes every derived number that depended on it, everywhere - and it is why you should not cache a rate much longer than you cache the sums it came from.

MVP scoring. Combat, support and objective run in the thousands while K/D sits near 1, so averaging them raw would make the award mean "combat" and nothing else. Each metric is instead expressed as a percentage of the best qualified player in the field, and those percentages are weighted: combat 40, K/D 30, support 15, objective 15. Qualifying means having played at least half as many matches as the deepest run in the bracket, rounded up. Placement is deliberately excluded - a player knocked out in groups who averaged huge games can still take it. If nobody scored in a metric at all, it is dropped and its weight shared among the rest, so the leader always reaches 100. The response spells out weights, min_matches, metrics_used and each player's per-metric parts.

Data caveats

Worth knowing before you build something on this data.

• Stats come from end-of-match screenshots. They are read automatically and can occasionally be wrong. Moderators correct them, which is exactly what /v1/matches/{id}/edits exposes - if a number matters, check whether it has been amended.
• Use placement, not placement_observed. Tournament matches sometimes share a public lobby with squads who are not in the bracket, so the on-screen position badge is not the tournament result. placement is the position among recognised squads.
• Non-tournament players appear in match detail. Anyone on the scoreboard is recorded, with in_tournament: false if they were not in the bracket. They are excluded from aggregates automatically, but they are present in /v1/matches/{id}.
• Players who disconnected are counted by default. They played the match and their partial line is the honest record of what they did. Pass exclude_disconnected=1 for full-match-only numbers. The one place they are always excluded is the class split - a greyed-out scoreboard row carries no class letter, so there is nothing to attribute.
• Team names repeat and change. They are unique only within a tournament. Match on team_id within an event and on roster Embark IDs across events.
• Some tournaments have a null name and are known only by their code. Fall back to the code for display.

Examples

Top 10 by K/D in one tournament, minimum 5 matches

curl -H "Authorization: Bearer $CB_KEY" \
  "https://api.stats.playrservers.com/v1/stats?group_by=player&tournament=CB-42WA\
&sort=kd&min_matches=5&limit=10"

One player's whole career

curl -H "Authorization: Bearer $CB_KEY" \
  "https://api.stats.playrservers.com/v1/players/SHADOW%237360"

Which map does a squad do best on?

curl -H "Authorization: Bearer $CB_KEY" \
  "https://api.stats.playrservers.com/v1/stats?group_by=map&team_id=17&sort=win_rate"

Node

const BASE = "https://api.stats.playrservers.com/v1";

async function cb(path, params = {}) {
  const url = new URL(BASE + path);
  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.CB_KEY}` },
  });
  const body = await res.json();
  if (!res.ok) {
    // Branch on the code, never on the message.
    if (body.error === "rate_limited") {
      const wait = Number(res.headers.get("Retry-After") || 5);
      await new Promise((r) => setTimeout(r, wait * 1000));
      return cb(path, params);
    }
    throw new Error(`${body.error}: ${body.message}`);
  }
  return body;
}

const { rows } = await cb("/stats", {
  group_by: "player", tournament: "CB-42WA", sort: "kd", min_matches: 5, limit: 10,
});
for (const p of rows) console.log(p.embark_id, p.kd, `${p.matches} matches`);

Python

import os, requests

BASE = "https://api.stats.playrservers.com/v1"
S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['CB_KEY']}"

def cb(path, **params):
    r = S.get(BASE + path, params=params, timeout=20)
    body = r.json()
    if not r.ok:
        raise RuntimeError(f"{body['error']}: {body['message']}")
    return body

# Every player, paged through in chunks of 500.
offset, everyone = 0, []
while True:
    page = cb("/stats", group_by="player", limit=500, offset=offset)
    everyone += page["rows"]
    offset += len(page["rows"])
    if offset >= page["total"] or not page["rows"]:
        break

print(len(everyone), "players")

Straight into a spreadsheet

curl -H "Authorization: Bearer $CB_KEY" \
  "https://api.stats.playrservers.com/v1/stats.csv?group_by=team&tournament=CB-42WA" \
  -o teams.csv