Live realm data for clan sites, Discord bots, and fan tools.
Read-only, JSON, open to cross-origin requests, so a clan site can call it straight from the browser. Access is by invitation — keys are issued by hand, so there is no signup form. See Getting a key.
There are two hosts, and the split is deliberate:
https://api.ageofsplendor.com | Realm-wide data. Same answers for everyone. Any key. |
https://clan.ageofsplendor.com | Your clan's own roster. Only your key, only your clan. |
Preferred — header. Send your key as X-API-Key, or as a bearer token:
curl -H "X-API-Key: aos_xxxxxxxx" https://api.ageofsplendor.com/status/lunaConvenience — in the path. Handy for pasting into a browser or a tool that cannot set headers. On the public host the key is the first segment; in a clan space it goes right after the clan name:
https://api.ageofsplendor.com/aos_xxxxxxxx/status/luna
https://clan.ageofsplendor.com/yourclan/aos_xxxxxxxx/membersKeys in a URL end up in web-server logs, browser history, and the Referer header of anything you link to. Use the header form for anything running server-side, and never put a path-key URL in public page markup.
Each key carries a list of scopes — status, castles, raids, olympiad, characters, clan — and a list of realms it may read. Calling an endpoint outside your scopes returns 403 missing_scope; a realm outside your list returns 403 realm_forbidden. Check yours with GET /me.
Everything on https://api.ageofsplendor.com is server-wide. Each resource returns every realm your key can read; append /{realm} for just one. Realms with no data for that resource are omitted from the list rather than returned as errors.
GET / | Service index. The only endpoint that works without a key. |
GET /me | Your key: scopes, readable realms, rate limit, clan space if any. |
GET /realms | Realm keys your key is allowed to read. |
GET /status | Players online. Add /{realm} for one realm. |
GET /castles | Castle owners and siege schedule. |
GET /raids | Raid and grand boss respawn state. |
GET /olympiad | Olympiad standings, current heroes, cycle and period. |
GET /characters/{name} | A character profile — the same data /profiles/{name} shows. Add /{realm}/{name} to pin the realm. |
GET https://api.ageofsplendor.com/status/luna
{
"realm": "luna",
"online": true,
"players": { "online": 412, "offlineShops": 88, "total": 500 },
"updatedAt": "2026-07-24T11:04:18.221Z"
}online counts real connected players, offlineShops the offline-trade characters, and total both together. On forks that do not mark offline shops, offlineShops is null and online equals total. The realm-level online flag means the game database answered.
GET https://api.ageofsplendor.com/castles/luna
[ { "id": 1, "name": "Gludio", "owner": "Ruination",
"siegeAt": "2026-08-02T18:00:00Z" } ]
GET https://api.ageofsplendor.com/raids/luna
[ { "bossId": 29020, "name": "Baium", "state": "dead",
"respawnAt": "2026-07-25T21:00:00Z", "grand": true } ]
GET https://api.ageofsplendor.com/olympiad/luna
{ "period": 1, "cycle": 14,
"heroes": [ { "charId": 101, "name": "Ayo", "classId": 88 } ],
"ranking": [ { "charId": 101, "name": "Ayo", "classId": 88, "points": 340,
"competitions": { "done": 12, "won": 9, "lost": 3 } } ] }Boss names come from the server's npc data where available, otherwise name is null and you match on bossId. Olympiad ranking is the top 100 by points. Classes are numeric ids.
Per-player data is never served from the public host. A clan key is bound at issue time to exactly one clan on one realm, and gets its own address:
https://clan.ageofsplendor.com/yourclan/membersThe clan name in the URL must match the one your key is bound to — pointing a valid key at another clan's space returns 403 clan_forbidden. Every query underneath is filtered by your clan id, so a character lookup only resolves for your own members:
GET /{clan} | Clan summary: level, leader, reputation, ally, member counts. |
GET /{clan}/me | The calling key, without touching the game database. |
GET /{clan}/members | Full roster with level, class, online state, last access. |
GET /{clan}/members/{charId} | One member by character id. 404 outside your clan. |
GET https://clan.ageofsplendor.com/yourclan/members/268476001
{ "realm": "luna", "clanId": 268476001,
"member": { "charId": 268476001, "name": "Ayo", "level": 80, "classId": 88,
"online": true, "offlineShop": false, "title": "Leader",
"pledgeRank": 0, "lastAccess": "2026-07-24T20:11:19Z",
"onlineTimeSeconds": 72000 } }A character id outside your clan returns exactly the same 404 member_not_found as one that does not exist, so the endpoint cannot be used to probe which ids are real.
Each key has a per-minute budget (60 by default). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (a Unix timestamp). Going over returns 429 with a Retry-After header.
Readings are cached server-side — 15s for status, 60s for castles and raids, 5min for olympiad — so polling faster than that gains you nothing. Cache on your side and poll once every 30–60 seconds; that is plenty for a status widget.
Failures return the matching HTTP status and a body of { "error": { "code", "message" } }. Branch on code, not on the message text.
401 | key_missing | No key in the header or the path. |
401 | key_invalid | Unknown or disabled key. |
401 | key_expired | The key is past its expiry date. |
403 | missing_scope | The key lacks the scope that endpoint needs. |
403 | realm_forbidden | The key is not allowed to read that realm. |
403 | not_a_clan_key | The key has no clan space. |
403 | clan_forbidden | The key belongs to a different clan space. |
404 | unknown_realm | No realm with that key exists. |
404 | member_not_found | No such character in your clan. |
404 | unknown_endpoint | No such endpoint. |
429 | rate_limited | Over your per-minute limit. See Retry-After. |
503 | status_unavailable | That realm is not wired to a game database. |
503 | resource_unavailable | This realm has no data for that resource. |
Clan leaders can register their clan — you confirm ownership of the leader's character through your master account, and staff approve the application. For anything else (fan sites, bots without a clan), ask on Discord with your site name, the URL it will run on, and roughly how often you plan to poll. Either way you get a key, the scopes and realms it covers, and its rate limit.
Treat the key like a password: keep it server-side, do not commit it, and tell us if it leaks so we can revoke it. A clan key reads your members' data — whoever holds it can see your whole roster. Confirm a key is live with GET /me.
The data is provided as-is, for fan sites and community tools. Do not resell it, do not use it to disrupt the game or other players, and please credit Age of Splendor where you display it. Keys that hammer the API or breach these terms get revoked.