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
- 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.
- Copy the key. It is shown once. Keep it in an environment variable, never in a web page.
- Call the API with it, as below. The answer is Test Team, an invented team, with the header X-GWL-Mode: test.
- 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.
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.
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
| Scope | Routes | Fields |
|---|---|---|
team.read | GET /api/v1/team | slug, name, tag, region, description, flag, flags, eloRating, ratedMatches, seasonMatches, placements, seasonPlacements, score, seasonScore, form, reputationScore, safetyBand, rosterCount, leagueRank |
members.read | GET /api/v1/team/members | members |
members.discord | Adds fields to another route | discordName on each member (GET /api/v1/team/members) |
members.discord_id | Adds fields to another route | discordId on each member (GET /api/v1/team/members) and each applicant (GET /api/v1/team/applications) |
members.steam_id | Adds fields to another route | steamId on each member (GET /api/v1/team/members) |
applications.read | GET /api/v1/team/applications | applications |
applications.write | POST /api/v1/team/applications/{id}/respond | id, accepted, name |
matches.read | GET /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.file | GET /api/v1/team/matches/{number}/file | id, map, startedAt, endedAt, reason, endReason, coverage, eventCount, events, scores, notice |
slots.read | GET /api/v1/team/slots | slots |
elo.read | GET /api/v1/team/elo | eloRating, ratedMatches, changeLast5, history |
public.read | GET /api/v1/standings, GET /api/v1/teams, GET /api/v1/teams/{slug}, GET /api/v1/matches, GET /api/v1/players/leaderboard | rank, 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.
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
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.
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.
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.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A query parameter or body field is missing, of the wrong type or out of range. |
| 400 | invalid_json | The body of a POST could not be read as JSON. |
| 401 | missing_key | No Authorization header, or not a bearer token. |
| 401 | invalid_key | Not a key, a mistyped one, or a key used in the wrong mode. |
| 401 | key_revoked | The key was revoked, by its team, by league staff or because its team is gone. |
| 401 | key_expired | The key passed the expiry chosen when it was made. |
| 403 | missing_scope | The key was made without the scope the route needs. The message names it. |
| 403 | scope_lost | The scope is ticked, but the key’s maker no longer holds the team permission behind it. |
| 403 | wrong_key_type | A personal key on a team route, or a team live key on a public route. |
| 403 | team_suspended | League staff suspended the team. Its keys work again when it is restored. |
| 403 | key_maker_left | The person who made or last rotated the key left the team. Rotating starts it again. |
| 403 | key_maker_no_access | The person who made or last rotated the key no longer holds Manage API keys. Rotating starts it again. |
| 404 | not_found | Nothing at that address, or another team’s match or application (so their existence does not leak). |
| 405 | method_not_allowed | The path exists for another method. The Allow header lists it. |
| 409 | application_closed | The application was accepted, declined, withdrawn or expired before your answer. |
| 413 | body_too_large | A POST body over 4 KB. |
| 415 | unsupported_media_type | A POST without Content-Type: application/json. |
| 429 | rate_limited | Over the per-minute limit for the key or the address. Wait for Retry-After. |
| 429 | daily_limit | A personal or test key used its requests for the day. |
| 429 | too_many_bad_keys | Too many wrong keys from one address. Wait for Retry-After. |
| 500 | internal_error | A fault on the league’s side. Try again later. |
| 503 | public_api_off | The league switched the public tier off for now. Team routes still work. |
Example body for each code
{
"error": {
"code": "invalid_request",
"message": "Check the query parameters."
}
}{
"error": {
"code": "invalid_json",
"message": "The body is not valid JSON."
}
}{
"error": {
"code": "missing_key",
"message": "Send your key as Authorization: Bearer <key>."
}
}{
"error": {
"code": "invalid_key",
"message": "That key is not valid."
}
}{
"error": {
"code": "key_revoked",
"message": "That key has been revoked."
}
}{
"error": {
"code": "key_expired",
"message": "That key has expired."
}
}{
"error": {
"code": "missing_scope",
"message": "This key does not have the team.read scope."
}
}{
"error": {
"code": "scope_lost",
"message": "Whoever made this key no longer has the power behind Team record. Someone who does can rotate it."
}
}{
"error": {
"code": "wrong_key_type",
"message": "That needs a team key."
}
}{
"error": {
"code": "team_suspended",
"message": "This team is suspended, so its keys are stopped."
}
}{
"error": {
"code": "key_maker_left",
"message": "Whoever made this key is no longer on the team. Someone with access can rotate it."
}
}{
"error": {
"code": "key_maker_no_access",
"message": "Whoever made this key can no longer manage API keys. Someone with access can rotate it."
}
}{
"error": {
"code": "not_found",
"message": "We could not find that."
}
}{
"error": {
"code": "method_not_allowed",
"message": "That method is not allowed here."
}
}{
"error": {
"code": "application_closed",
"message": "That application has already ended."
}
}{
"error": {
"code": "body_too_large",
"message": "That body is too large."
}
}{
"error": {
"code": "unsupported_media_type",
"message": "Send the body as application/json."
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests for this key."
}
}{
"error": {
"code": "daily_limit",
"message": "This key has used today’s requests."
}
}{
"error": {
"code": "too_many_bad_keys",
"message": "Too many bad keys from this address."
}
}{
"error": {
"code": "internal_error",
"message": "Something went wrong on our side."
}
}{
"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.
