Getting started
All endpoints below use API v2. The base path is /api/v2/public. Paths in the tables are relative to this prefix.
Send list parameters as a JSON object in the POST body with Content-Type: application/json. Use {} for an unfiltered request. GET requests need no body. Query string parameters such as ?page=… are not supported.
The selected site determines the language and game version. To select a site explicitly, send X-Site with its full hostname, such as allodswiki.ru or en.allodswiki.ru. Otherwise Origin/Host is used. The language and game version cannot be selected through the request body or query string.
Reading is available without signing in, subject to the guest rate limit. Applications can use an API token created in the profile, sent as Authorization: Bearer <token>. User-Agent must exactly match the value configured for that token. The standard limit applies until approval; an administrator then assigns the approved limit.
Game database resources
{id} is the numeric resource identifier shown on the website. It is also returned by lists and related resources. Names and slugs from website page URLs are not part of the API path. Only published resources for the selected game version are returned.
| Resource | List | Details | Tooltip |
|---|---|---|---|
| Items | POST /items | GET /items/{id} | GET /items/{id}/tooltip |
| Quests | POST /quests | GET /quests/{id} | GET /quests/{id}/tooltip |
| NPCs and creatures | POST /mobs | GET /mobs/{id} | GET /mobs/{id}/tooltip |
| Objects | POST /objects | GET /objects/{id} | GET /objects/{id}/tooltip |
| Zones | POST /zones | GET /zones/{id} | GET /zones/{id}/tooltip |
| Achievements | POST /achievements | GET /achievements/{id} | GET /achievements/{id}/tooltip |
| Spells | POST /spells | GET /spells/{id} | GET /spells/{id}/tooltip |
| Abilities | POST /abilities | GET /abilities/{id} | GET /abilities/{id}/tooltip |
| Skills | POST /unlocks | GET /unlocks/{id} | GET /unlocks/{id}/tooltip |
| Currencies | POST /currencies | GET /currencies/{id} | GET /currencies/{id}/tooltip |
| Factions | POST /factions | GET /factions/{id} | GET /factions/{id}/tooltip |
List parameters
A regular list returns {"items": [...], "total": 123}. Each page contains up to 50 entries, starting at page 1. total is the number of matches before pagination. The page size is fixed: limit, offset and page_size are not used.
| Field | Value and purpose |
|---|---|
| page | Integer of at least 1; defaults to 1. |
| search | Optional name search, 3–256 characters. Omit the field when no search is needed; an empty string is not valid. |
| desc | Boolean controlling search sort direction. Most lists without a search use ascending name order; quests and creatures have their own sort and desc options. |
| quality | /items only: the item quality code used in the response quality field. |
| level_min, level_max | /quests and /mobs only: optional integer level bounds. Either bound can be supplied alone; the upper bound must not be lower than the lower bound. Creature level ranges are matched by intersection. |
| sort | /quests and /mobs only: name or level; desc controls the direction. |
| faction | /quests only: league or empire. Omit the field for all factions; all is not an accepted value. |
Ranks and achievement stages
/abilities/{id}/tooltip and /spells/{id}/tooltip contain a ranks array. Use the dedicated endpoints below for one rank. {rank} is a positive rank number starting at 1.
For achievements, take {stage_id} from stages[].id in the achievement details. It is a stage identifier, not its position, and is only used together with the parent achievement ID.
| Method and path | Purpose |
|---|---|
| GET /abilities/{id}/ranks/{rank}/tooltip | Tooltip for one ability rank. |
| GET /spells/{id}/ranks/{rank}/tooltip | Tooltip for one spell rank. |
| GET /achievements/{id}/stages/{stage_id}/tooltip | Tooltip for one achievement stage. |
World Mysteries
| Method and path | Purpose |
|---|---|
| POST /secrets | Complete World Mysteries list; body {}. Returns {"items": [...]} without total or pagination. |
| GET /secrets/{id} | World Mystery details, including stages, quest graphs and rewards. There is no separate tooltip endpoint. |
Talent calculator
| Method and path | Purpose |
|---|---|
| GET /character-classes | Class directory: {"data": [{"name": "…", "slug": "…"}]}. |
| GET /talents/{name} | Calculator for the selected class in the site’s current game version. |
| GET /talents/{name}/layouts/{layout_id} | A specific available layout for that class. |
{name} is the slug returned by /character-classes. Use layout.id from the calculator response as {layout_id}; it is an opaque, class-specific layout identifier, not a game version number.
Both calculator endpoints return name, point_budget, layout, spells, abilities, layers, fields and relations. layout contains id and last_seen_version. layers describes talent rows and point requirements; fields describes ruby grids and starting cells; relations links abilities and spells. Read the geometry from the response rather than assuming fixed dimensions.
The talents and rubies groups in point_budget contain level_free, level_subscription, total_free and total_subscription. Use the returned values: point budgets depend on the selected game version.
Armory
| Method and path | Purpose |
|---|---|
| POST /armory/avatars | Up to 100 characters ordered by level and gear score. Returns {"items": [...], "servers": [...]}, without pagination or total. |
| GET /armory/avatars/{id} | A character by their character ID on the website, including equipment and update time. |
POST /armory/avatars accepts optional search, server and class_key fields. search is an exact character name of up to 256 characters, matched case-insensitively; Russian е and ё remain distinct. server is the server identifier from servers[].id, and class_key is the class code (slug from /character-classes). Send {} for no filters.
Character list entries contain id, name, guild, level, gear_score, class, race, faction and server. class and race are codes rather than translated labels. Hidden or deleted characters and servers are excluded.
The detail response also contains greatness, updated_at and equipment. Each equipment entry has position, place and item. An item missing from the database has item.id set to null and unknown set to true; its stats may still be available. updated_at is the source time without a UTC offset.
Request examples
curl -X POST 'https://en.allodswiki.ru/api/v2/public/items' -H 'Content-Type: application/json' --data '{"page":1}'
curl -X POST 'https://en.allodswiki.ru/api/v2/public/quests' -H 'Content-Type: application/json' --data '{"page":1,"level_min":60,"level_max":70,"faction":"league","sort":"level","desc":true}'
curl 'https://en.allodswiki.ru/api/v2/public/character-classes'
curl 'https://en.allodswiki.ru/api/v2/public/talents/warrior'
curl -X POST 'https://en.allodswiki.ru/api/v2/public/armory/avatars' -H 'Content-Type: application/json' --data '{}'
Responses and limits
Successful requests return HTTP 200 and JSON without an additional common envelope. Detail and tooltip fields depend on the resource type; tooltips are separate, smaller responses.
/zones/{id} may return HTTP 200 with {"redirect_id": 123} when a subzone belongs to a root zone. Continue reading with that ID.
Errors use {"error": {"code": "…", "message": "…"}}. For HTTP 422 validation_failed, error.fields contains parameter errors. HTTP 404 game_resource_not_found indicates an unavailable resource; armory_character_not_found indicates a character; talent_layout_not_found indicates a layout.
X-RateLimit-Limit gives the current request limit, and X-RateLimit-Remaining gives the remaining number of requests. After HTTP 429 too_many_requests, wait for Retry-After; X-RateLimit-Reset gives the reset time in Unix seconds.