The API

The league has an API for your own tools: a bot, a dashboard, a stats sheet. A team key reads the team’s own data and can answer applications. A personal key reads only what is already public. A test key reads invented data, so you can build before you touch anything real.

Quick start in 2 minutes

  1. Open Team Settings, API access, and press Make a key. Choose Test key, tick Team record and press Make test key. Any team can do this, whatever its size.
  2. Copy the key. It is shown once. Keep it in an environment variable, never in a web page.
  3. Call the API with it, as below. The answer is Test Team, an invented team, with the header X-GWL-Mode: test.
  4. When your tool works, make a live key with the same scopes and swap it in. Nothing else changes: same paths, same fields, same errors.
Your first call
export GWL_API_KEY=gwl_test_abcd2345_examplesecretexamplesecretexamplesecret2
curl "https://YOUR-LEAGUE-ADDRESS/api/v1/team" \
  -H "Authorization: Bearer $GWL_API_KEY"

Every route, with curl, JavaScript and Python and a real example answer, is in the API reference. The OpenAPI document at /api/v1/openapi.json describes the same, for code generators and API tools.

Test mode

A test key starts gwl_test_ instead of gwl_live_. It works at the same addresses, with the same header, the same scopes, the same answers and the same errors as a live key, but every answer comes from a sandbox of invented data: Test Team and its eight members, ten invented teams, matches, applications, open slots, an Elo history and a leaderboard. No real team, person or id is ever in it, and the sandbox reads nothing from the league.

  • The same people who make live keys make test keys, with no roster minimum. A team can hold 5 test keys on top of its live ones.
  • A test key gets 30 requests a minute and 1,000 a day.
  • Every answer to a test key carries the header X-GWL-Mode: test. A live key’s answers never do.
  • The data never changes: dates sit around 2027-01-15, so the same call gives the same answer today and next year. Compare dates with each other, not with today.
  • A test key with the Public league data scope also reads the sandbox’s standings, teams, results and leaderboard.
  • Scopes are checked as for a live key: a scope you could not tick on a live key you cannot tick on a test key either, and a key whose maker loses the power stops the same way.
  • Answering an application works, but only in the sandbox: nothing is saved and nobody is told. The sandbox remembers your answers for 10 minutes (so the application leaves the list and a second answer is refused), or until you call POST /api/v1/test/reset.
  • A live key and a test key are never interchangeable: a live key sent as gwl_test_, or the other way, is not a key.

Add ?scenario=<name> to any call to see another state of the team. GET /api/v1/test/scenarios lists them; a live key gets 404 there and its scenario is ignored.

default
Test Team with 8 members, 2 upcoming and 3 recent matches, 2 applications and 2 open slots. Used when no scenario is given.
empty-team
A team made today: only its Team Leader, no matches, applications, slots or Elo history, and no rank.
busy-week
A busy week: 7 upcoming and 4 recent matches (one disputed), 6 applications and 5 open slots.
full-roster
The default team with a full roster of 32.
errors
Every call answers an error: the one named by force_error, or internal_error without it.

Add ?force_error=<code> to any call to get that error, with its status and headers, so you can test how your tool handles it. Every code in the Errors table works.

Try your error handling
curl -i "https://YOUR-LEAGUE-ADDRESS/api/v1/team?force_error=scope_lost" \
  -H "Authorization: Bearer $GWL_API_KEY"

Getting a key

  • Team keys: the Team Leader makes them, or anyone given a team role with Manage API keys, in Team Settings, API access. A live key needs at least 5 on the roster; a key you already have keeps working if it drops below that.
  • A team can have 5 live keys. Each has a name, the scopes you tick and an expiry of 30, 90, 365 days or none.
  • Personal keys: anyone with Steam linked who has played in a confirmed league match gets a Developer access section on their account page, for up to 2 keys. They read only public data and end by themselves if Steam is unlinked.
  • A key is shown once. If you lose it, rotate it: the same key gets a new secret and the old one stops at once.
  • A key can only do what its maker could do. If they leave the team or can no longer manage API keys, it pauses; rotating it starts it again under the person who rotated it.

Scopes at a glance

Each scope, the routes it opens and the fields they answer with
ScopeRoutesFields
team.readGET /api/v1/teamslug, name, tag, region, description, flag, flags, eloRating, ratedMatches, seasonMatches, placements, seasonPlacements, score, seasonScore, form, reputationScore, safetyBand, rosterCount, leagueRank
members.readGET /api/v1/team/membersmembers
members.discordAdds fields to another routediscordName on each member (GET /api/v1/team/members)
members.discord_idAdds fields to another routediscordId on each member (GET /api/v1/team/members) and each applicant (GET /api/v1/team/applications)
members.steam_idAdds fields to another routesteamId on each member (GET /api/v1/team/members)
applications.readGET /api/v1/team/applicationsapplications
applications.writePOST /api/v1/team/applications/{id}/respondid, accepted, name
matches.readGET /api/v1/team/fixtures, GET /api/v1/team/matches/{number}upcoming, recent; number, status, rated, region, map, layer, weather, season, startsAt, concludedAt, durationSeconds, host, sides, lockedAt, serverPosted, readyTeams
matches.fileGET /api/v1/team/matches/{number}/fileid, map, startedAt, endedAt, reason, endReason, coverage, eventCount, events, scores, notice
slots.readGET /api/v1/team/slotsslots
elo.readGET /api/v1/team/eloeloRating, ratedMatches, changeLast5, history
public.readGET /api/v1/standings, GET /api/v1/teams, GET /api/v1/teams/{slug}, GET /api/v1/matches, GET /api/v1/players/leaderboardrank, team, name, tag, region, played, wins, placements, score, eloRating, form, reputation, mainFaction; slug, name, tag, region, flag, flags, eloRating, reputationScore, safetyBand, provisional, ratedMatches, seasonMatches, placements, rosterCount, mainFaction, openSlots, rank; slug, name, tag, region, description, flag, flags, eloRating, ratedMatches, placements, reputationScore, safetyBand, rosterCount, rank, founders, roster; number, status, rated, region, map, layer, weather, season, startsAt, concludedAt, durationSeconds, host, sides; rank, playerId, name, team, region, eloRating, matches, wins, winRate, country

What is private

  • Personal keys never return a Steam ID or a Discord ID, and read only what the website shows to anyone.
  • A team key returns Discord IDs and Steam IDs only with the two ID scopes below, and only for that team’s own members.
  • Discord names need the members.discord scope, on a key whose maker can see them, and are only for that team’s own members.
  • Server addresses and passwords are never returned.

Personal identifiers

Teams build rosters, bots and server whitelists on Discord and Steam IDs, so a team key can carry them. Personal identifiers. Anyone holding this key can read them. Keep it inside your team’s tools.

  • members.discord_id adds each member’s Discord account ID (discordId) on /team/members, and each applicant’s on /team/applications. The key’s maker must be able to see the team’s private roster details, the same as for Discord names.
  • members.steam_id adds each member’s SteamID64 (steamId) on /team/members. Only the Team Leader can tick it, because only the Team Leader sees raw Steam IDs.
  • Either one also ticks Members. Without the scope the field is not in the answer at all; with it, a person who has not linked that account reads null.
  • An applicant’s Steam ID is never returned: they are not on the team yet. Mercenaries are not members and are not listed.
  • If the maker can no longer tick the scope (they left the Leader role, or lost the permission), the key answers 403 scope_lost until someone who can rotates it.
  • When someone other than the Team Leader makes or rotates a key with an ID scope, the Team Leader is told. Every key made or rotated is on the league’s audit log with its scopes.
  • Everyone on a team reads on their account page: “Your team’s Leader, or someone they have trusted with API keys, can let tools read your Discord ID; only the Leader can include your Steam ID.”
  • A test key with these scopes gets invented IDs that can never be a real person’s: SteamID64s below the first real account and Discord IDs from before Discord launched.

Limits and headers

  • Team live key: 120 requests a minute. Pages up to 100.
  • Test key: 30 a minute and 1,000 a day.
  • Personal key: 60 a minute and 5,000 a day. Pages up to 50, 10 pages deep.
  • Each address: 300 requests a minute, and 20 bad keys a minute.
  • Over a limit is a 429 with Retry-After, in seconds. Wait that long, then go on.
The headers of an answer
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-API-Version: 1
X-GWL-Mode: test
ETag: "q1w2e3r4t5y6u7i8o9p0a1s2d3f"
Cache-Control: private, no-cache
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1800000060
X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 999
Over the limit
HTTP/1.1 429 Too Many Requests
Retry-After: 21
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this key."
  }
}

Caching with ETag

Every GET answer has an ETag. Send it back as If-None-Match and, when nothing changed, the answer is an empty 304. A 304 still counts against the limits, but it is quicker for you.

Asking again with If-None-Match
curl -i "https://YOUR-LEAGUE-ADDRESS/api/v1/team" \
  -H "Authorization: Bearer $GWL_API_KEY" \
  -H 'If-None-Match: "q1w2e3r4t5y6u7i8o9p0a1s2d3f"'

HTTP/1.1 304 Not Modified
ETag: "q1w2e3r4t5y6u7i8o9p0a1s2d3f"

Paging

Public lists answer a page at a time: items, page, limit, total and hasMore. Ask for the next page while hasMore is true.

Every page, in JavaScript
async function allTeams() {
  const teams = []
  for (let page = 1; ; page++) {
    const res = await fetch(`https://YOUR-LEAGUE-ADDRESS/api/v1/teams?limit=50&page=${page}`, {
      headers: { Authorization: `Bearer ${process.env.GWL_API_KEY}` },
    })
    const body = await res.json()
    teams.push(...body.items)
    if (!body.hasMore) return teams
  }
}

Errors

Every error is JSON: { "error": { "code": "...", "message": "..." } }. The code never changes, so match on it; the message is for people and may change.

Every error code
StatusCodeWhen
400invalid_requestA query parameter or body field is missing, of the wrong type or out of range.
400invalid_jsonThe body of a POST could not be read as JSON.
401missing_keyNo Authorization header, or not a bearer token.
401invalid_keyNot a key, a mistyped one, or a key used in the wrong mode.
401key_revokedThe key was revoked, by its team, by league staff or because its team is gone.
401key_expiredThe key passed the expiry chosen when it was made.
403missing_scopeThe key was made without the scope the route needs. The message names it.
403scope_lostThe scope is ticked, but the key’s maker no longer holds the team permission behind it.
403wrong_key_typeA personal key on a team route, or a team live key on a public route.
403team_suspendedLeague staff suspended the team. Its keys work again when it is restored.
403key_maker_leftThe person who made or last rotated the key left the team. Rotating starts it again.
403key_maker_no_accessThe person who made or last rotated the key no longer holds Manage API keys. Rotating starts it again.
404not_foundNothing at that address, or another team’s match or application (so their existence does not leak).
405method_not_allowedThe path exists for another method. The Allow header lists it.
409application_closedThe application was accepted, declined, withdrawn or expired before your answer.
413body_too_largeA POST body over 4 KB.
415unsupported_media_typeA POST without Content-Type: application/json.
429rate_limitedOver the per-minute limit for the key or the address. Wait for Retry-After.
429daily_limitA personal or test key used its requests for the day.
429too_many_bad_keysToo many wrong keys from one address. Wait for Retry-After.
500internal_errorA fault on the league’s side. Try again later.
503public_api_offThe league switched the public tier off for now. Team routes still work.
Example body for each code
400 invalid_request
{
  "error": {
    "code": "invalid_request",
    "message": "Check the query parameters."
  }
}
400 invalid_json
{
  "error": {
    "code": "invalid_json",
    "message": "The body is not valid JSON."
  }
}
401 missing_key
{
  "error": {
    "code": "missing_key",
    "message": "Send your key as Authorization: Bearer <key>."
  }
}
401 invalid_key
{
  "error": {
    "code": "invalid_key",
    "message": "That key is not valid."
  }
}
401 key_revoked
{
  "error": {
    "code": "key_revoked",
    "message": "That key has been revoked."
  }
}
401 key_expired
{
  "error": {
    "code": "key_expired",
    "message": "That key has expired."
  }
}
403 missing_scope
{
  "error": {
    "code": "missing_scope",
    "message": "This key does not have the team.read scope."
  }
}
403 scope_lost
{
  "error": {
    "code": "scope_lost",
    "message": "Whoever made this key no longer has the power behind Team record. Someone who does can rotate it."
  }
}
403 wrong_key_type
{
  "error": {
    "code": "wrong_key_type",
    "message": "That needs a team key."
  }
}
403 team_suspended
{
  "error": {
    "code": "team_suspended",
    "message": "This team is suspended, so its keys are stopped."
  }
}
403 key_maker_left
{
  "error": {
    "code": "key_maker_left",
    "message": "Whoever made this key is no longer on the team. Someone with access can rotate it."
  }
}
403 key_maker_no_access
{
  "error": {
    "code": "key_maker_no_access",
    "message": "Whoever made this key can no longer manage API keys. Someone with access can rotate it."
  }
}
404 not_found
{
  "error": {
    "code": "not_found",
    "message": "We could not find that."
  }
}
405 method_not_allowed
{
  "error": {
    "code": "method_not_allowed",
    "message": "That method is not allowed here."
  }
}
409 application_closed
{
  "error": {
    "code": "application_closed",
    "message": "That application has already ended."
  }
}
413 body_too_large
{
  "error": {
    "code": "body_too_large",
    "message": "That body is too large."
  }
}
415 unsupported_media_type
{
  "error": {
    "code": "unsupported_media_type",
    "message": "Send the body as application/json."
  }
}
429 rate_limited
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this key."
  }
}
429 daily_limit
{
  "error": {
    "code": "daily_limit",
    "message": "This key has used today’s requests."
  }
}
429 too_many_bad_keys
{
  "error": {
    "code": "too_many_bad_keys",
    "message": "Too many bad keys from this address."
  }
}
500 internal_error
{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side."
  }
}
503 public_api_off
{
  "error": {
    "code": "public_api_off",
    "message": "The public API is switched off."
  }
}

Version

This is version 1: every address starts /api/v1 and every answer carries X-API-Version: 1.

Questions

How do I rotate a key?
Rotate in Team Settings, API access. You get a new secret for the same key, scopes and expiry, and the old secret stops at once, so put the new one in place first.
My key says key_maker_no_access. Why?
Whoever made or last rotated it can no longer manage API keys. The key is paused, not revoked: someone who can manage keys rotates it and it works again under them. key_maker_left is the same when they left the team.
I keep getting 429.
Read Retry-After and wait that long. Use ETags so unchanged answers cost less, and fetch in a loop no faster than you need: matches and standings change a few times a day.
How soon does a change show?
Revoking or rotating a key works within 10 seconds, usually at once. Public answers may be up to 30 seconds old; team answers are fresh.
Can I call it from a web page?
Not with a team key: team routes send no CORS headers, because a key in a page is a key anyone can copy. Call it from your server or bot. Public routes allow browser GETs, but your key still travels with them.
Why are IDs behind scopes?
A name can change and an id never does, so an id can link a person across sites. Discord and Steam IDs reach a tool only when someone with the power ticks that scope for it, and only for the team’s own members (and, for Discord IDs, its applicants).
Does a test key cost my team anything?
No. It never touches real data, it does not count towards the live key cap and nobody is told about anything it does.

Next