API reference

A read-only census API. Everything below is a GET, and a key reads exactly what a signed-in person reads — no more.

Authentication

Send your key in either header. Nothing else authenticates a request, and a key sent to a route that is not listed here is refused rather than served.

X-Api-Key: wos_YOUR_KEY

Or, as a bearer token

Authorization: Bearer wos_YOUR_KEY

Quickstart

Replace the key with your own.

curl -H "X-Api-Key: wos_YOUR_KEY" \ "https://api.wosatlas.com/v1/players/search?playerName=LordFrost"

Endpoints

Method	Path	What it returns	Counts as
GET	/v1/alliances/{aid}/members	Fetch one alliance and its roster	Request
GET	/v1/alliances/leaderboard	Rank alliances by total power	Request
GET	/v1/alliances/recruiting	List alliances taking applications	Request
GET	/v1/alliances/search	Search alliances by tag or name	Search
GET	/v1/players/{uid}	Fetch one player by internal uid	Request
GET	/v1/players/search	Search players by name or Chief ID	Search

Plans and limits

Current operating values, not an entitlement. They can change.

Every limit is per account. Extra keys do not buy extra budget.

Both quota windows are ROLLING, not calendar periods: the read window looks back thirty days from now and the search window looks back twenty-four hours from now. Quota and search windows are metered per ACCOUNT, not per key — every key an account holds draws on one budget.

Response headers

A served response carries all of these, and so does a quota refusal. A burst refusal carries the three X-RateLimit headers alone, and a request refused before metering — 401 or 403 — carries none.

Header	Meaning
X-Quota-Limit	The account's read allowance for the rolling thirty-day window.
X-Quota-Remaining	Reads left in that window.
X-Quota-Reset	Unix seconds at which the oldest read in the window ages out.
X-Search-Limit	The account's search allowance for the rolling twenty-four-hour window.
X-Search-Remaining	Searches left in that window.
X-Search-Reset	Unix seconds at which the oldest search in the window ages out.
X-RateLimit-Limit	The account's burst allowance for the short window.
X-RateLimit-Remaining	Requests left in the burst window.
X-RateLimit-Reset	Unix seconds at which the burst window rolls.
Retry-After	Seconds to wait before retrying. Sent on every 429, and specific to the window that denied.

Being refused

Three different things answer with a 429, and they are not interchangeable.

Error code	What happened
QUOTA_EXCEEDED	The account's rolling thirty-day read quota is spent. `X-Quota-Remaining` reads zero; `X-Search-Remaining` stays honest.
SEARCH_QUOTA_EXCEEDED	The account's rolling twenty-four-hour search quota is spent. `X-Search-Remaining` reads zero; `X-Quota-Remaining` stays honest. Only the two search routes count against it.
RATE_LIMIT_EXCEEDED	The account's short burst window is full. `X-RateLimit-Remaining` reads zero. This is a per-second-scale ceiling and clears on its own; neither quota window has been touched.

Take the retry decision from the `error` code and the `Retry-After` header, never from a remaining counter. A monthly denial and a daily-search denial are both 429 and both leave the OTHER window's remaining counter truthfully non-zero, so a client watching only `X-Quota-Remaining` will see a 429 beside a large remaining count and conclude the server is broken.

Error codes

Code	Status	Meaning
INVALID_API_KEY	401	The key is unknown, revoked, or its owning account has been deleted.
ENDPOINT_NOT_ALLOWED	403	The route is not on the developer surface. Presenting a key on a route off the surface is refused rather than served, so do not send a key to endpoints this document does not list.
QUOTA_EXCEEDED	429	The account's rolling thirty-day read quota is spent. `X-Quota-Remaining` reads zero; `X-Search-Remaining` stays honest.
SEARCH_QUOTA_EXCEEDED	429	The account's rolling twenty-four-hour search quota is spent. `X-Search-Remaining` reads zero; `X-Quota-Remaining` stays honest. Only the two search routes count against it.
RATE_LIMIT_EXCEEDED	429	The account's short burst window is full. `X-RateLimit-Remaining` reads zero. This is a per-second-scale ceiling and clears on its own; neither quota window has been touched.

Machine-readable spec

The OpenAPI document below is generated from the running server and is the same one this page renders.

Download openapi.json

Terms