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, drops, olympiad, characters, clans (the public clan directory), clan (your own clan space) — 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 /drops | Recent raid kills with killer, clan and every item dropped. |
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 /characters/{objectId} | The same profile by character object id, e.g. /characters/268476001. |
GET /clans/{name} | Clan summary: level, leader, reputation, ally, castle, member counts. /clans/{clanId} works too. |
GET /clans/{name}/members | That clan’s roster: level, class, online state, last access. |
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 wiki's monster registry; an id the wiki does not know has name: null, so treat bossId as the key. Olympiad ranking is the top 100 by points. Classes are numeric ids.
GET https://api.ageofsplendor.com/drops/luna
{ "kills": [
{ "id": "29020-1753477200000", "bossId": 29020, "bossName": "Baium",
"bossLevel": 80, "grand": true, "killedAt": 1753477200000,
"lastHit": { "char": "Ayo", "clanId": 268476001, "clan": "Ruination", "ally": "Dawnbreakers" },
"drops": [
{ "itemId": 57, "itemName": "Adena", "count": 4200000,
"itemIcon": "https://ageofsplendor.com/img/icons/etc_adena_i00.webp" } ],
"participants": [
{ "char": "Ayo", "clanId": 268476001, "clan": "Ruination", "damage": 184220 } ] } ] }Newest kill first, capped at the most recent 500 drop rows per realm. The same items the server announces in-game — nothing private, no full inventory. Only realms whose game server has raid drop logging switched on return anything; the rest are omitted.bossName, itemName and itemIcon are best-effort from the wiki registry — an id the wiki does not know has them null, so keep bossId/itemId as the keys. killedAt is epoch milliseconds. id groups the rows of one kill and is stable, so it works as a de-duplication key when you poll. participants is every character who damaged the boss, highest damage first, with summon damage folded into the owner; it is empty on a realm that logs drops but not participation.
GET https://api.ageofsplendor.com/characters/Ayo # or /characters/268476123
{ "character": { "charId": 268476123, "name": "Ayo", "level": 85, "classId": 88,
"online": true, "clan": { "id": 268476001, "name": "Ruination" } } }
GET https://api.ageofsplendor.com/clans/Ruination # or /clans/268476001
{ "realm": "luna",
"clan": { "clanId": 268476001, "name": "Ruination", "level": 8,
"leader": { "charId": 268476123, "name": "Ayo" },
"reputation": 41500, "allyName": "Dawnbreakers", "castleId": 1,
"memberCount": 62, "onlineCount": 9 } }
GET https://api.ageofsplendor.com/clans/Ruination/members
{ "realm": "luna", "clan": { "clanId": 268476001, "name": "Ruination" },
"members": [ { "charId": 268476123, "name": "Ayo", "level": 85, "classId": 88,
"online": true, "pledgeRank": 0,
"lastAccess": "2026-07-24T11:04:18.221Z" } ] }Both accept a name or a numeric id — the object id for a character, the clan id for a clan — and an id is the stable one, since names get changed. Without a realm segment the realms your key can read are tried in order and the first match wins; put /{realm}/ in front of the name to pin one, e.g. https://api.ageofsplendor.com/clans/luna/Ruination/members. Unknown names return 404; a realm whose database is down is skipped, and 503 only comes back when every candidate realm failed.
The public host serves the public view: a clan's roster as anyone sees it in game. A clan's own space — applications, settings, anything only its leaders should read — is a clan key bound at issue time to exactly one clan on one realm, with 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, raids and drops, 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 | unknown_character | No character with that name or object id. |
404 | unknown_clan | No clan with that name or id. |
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. |
Personal key — self-service. Any master account can issue its own read-only key at https://clan.ageofsplendor.com/apikey — sign in, one click, done. It covers all the public endpoints above; rotate it there any time.
Clan key. Clan leaders register their clan — you confirm ownership of the leader's character through your master account, and staff approve the application. For anything bigger (fan sites, high-volume bots), ask on Discord with your site name, the URL it will run on, and roughly how often you plan to poll.
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.