Подключение
Все маршруты ниже относятся к API v2. Базовый путь — /api/v2/public. В таблицах указан путь относительно этого префикса.
Отправляйте параметры списков JSON-объектом в теле POST с заголовком Content-Type: application/json. Для запроса без фильтров достаточно {}. GET не требует тела. Параметры строки запроса (?page=… и подобные) не поддерживаются.
Все запросы отправляются на https://api.allodswiki.ru/api/v2/public. Пути в таблицах указаны относительно этого адреса. Заголовок X-Site: allodswiki.ru явно выбирает русский сайт и его версию игры. При прямом запросе к API без X-Site и Origin используется основной сайт — allodswiki.ru.
Чтение доступно без входа в пределах гостевого лимита. Для приложения можно создать API-токен в профиле и передавать Authorization: Bearer <token>. User-Agent должен полностью совпадать с указанным в настройках токена. До одобрения администрацией действует обычный лимит, после — назначенный администратором.
Ресурсы игровой базы
{id} — числовой идентификатор ресурса, указанный на сайте. Его также можно получить из ответа списка или связанного ресурса. Название и slug из адреса страницы сайта не входят в API. В ответах доступны только опубликованные ресурсы выбранной версии игры.
| Раздел | Список | Подробности | Подсказка |
|---|---|---|---|
| Предметы | POST /items | GET /items/{id} | GET /items/{id}/tooltip |
| Задания | POST /quests | GET /quests/{id} | GET /quests/{id}/tooltip |
| НПС и существа | POST /mobs | GET /mobs/{id} | GET /mobs/{id}/tooltip |
| Объекты | POST /objects | GET /objects/{id} | GET /objects/{id}/tooltip |
| Локации | POST /zones | GET /zones/{id} | GET /zones/{id}/tooltip |
| Достижения | POST /achievements | GET /achievements/{id} | GET /achievements/{id}/tooltip |
| Заклинания | POST /spells | GET /spells/{id} | GET /spells/{id}/tooltip |
| Способности | POST /abilities | GET /abilities/{id} | GET /abilities/{id}/tooltip |
| Навыки | POST /unlocks | GET /unlocks/{id} | GET /unlocks/{id}/tooltip |
| Валюты | POST /currencies | GET /currencies/{id} | GET /currencies/{id}/tooltip |
| Фракции | POST /factions | GET /factions/{id} | GET /factions/{id}/tooltip |
Параметры списков
Обычный список возвращает {"items": [...], "total": 123}. На странице до 50 записей; нумерация начинается с 1. total — количество совпадений до разбиения на страницы. Размер страницы не настраивается: limit, offset и page_size не используются.
| Поле | Значение и назначение |
|---|---|
| page | Целое число от 1; по умолчанию 1. |
| search | Необязательный поиск по названию, от 3 до 256 символов. Если поиск не нужен, не передавайте поле; пустая строка не подходит. |
| desc | Логическое значение. Управляет направлением сортировки поиска. Большинство списков без поиска идут по имени по возрастанию; у заданий и существ действуют собственные sort и desc. |
| quality | Только /items: строковый код качества предмета, используемый в поле quality ответа. |
| level_min, level_max | Только /quests и /mobs: необязательные целочисленные границы уровня. Можно передать одну границу; верхняя не должна быть ниже нижней. Для существ проверяется пересечение диапазонов уровней. |
| sort | Только /quests и /mobs: name или level; desc задаёт направление. |
| faction | Только /quests: league или empire. Для всех фракций поле пропускается; значение all не принимается. |
Ранги и этапы достижений
Подсказки /abilities/{id}/tooltip и /spells/{id}/tooltip содержат массив ranks. Для одного ранга используйте отдельный маршрут ниже. {rank} — положительный номер ранга, начиная с 1.
Для достижения {stage_id} берётся из stages[].id его подробного ответа. Это идентификатор этапа, а не порядковый номер; он используется только вместе с ID родительского достижения.
| Метод и путь | Назначение |
|---|---|
| GET /abilities/{id}/ranks/{rank}/tooltip | Подсказка выбранного ранга способности. |
| GET /spells/{id}/ranks/{rank}/tooltip | Подсказка выбранного ранга заклинания. |
| GET /achievements/{id}/stages/{stage_id}/tooltip | Подсказка конкретного этапа достижения. |
Тайны Мира
| Метод и путь | Назначение |
|---|---|
| POST /secrets | Полный список Тайн Мира; тело {}. Ответ {"items": [...]} без total и пагинации. |
| GET /secrets/{id} | Подробности Тайны Мира: этапы, графы заданий и награды. Отдельного маршрута подсказки нет. |
Калькулятор талантов
| Метод и путь | Назначение |
|---|---|
| GET /character-classes | Справочник классов: {"data": [{"name": "…", "slug": "…"}]}. |
| GET /talents/{name} | Калькулятор выбранного класса для текущей версии игры сайта. |
| GET /talents/{name}/layouts/{layout_id} | Конкретная доступная раскладка этого класса. |
{name} — значение slug из /character-classes. layout.id берётся из ответа калькулятора и подставляется как {layout_id}; это непрозрачный идентификатор раскладки внутри класса, а не номер версии игры.
Оба маршрута калькулятора возвращают name, point_budget, layout, spells, abilities, layers, fields и relations. layout содержит id и last_seen_version. layers описывает ряды талантов и требования по очкам, fields — поля вех и стартовые клетки, relations — связи способностей и заклинаний. Геометрию берите из ответа, а не задавайте фиксированными размерами.
В point_budget группы talents и rubies содержат level_free, level_subscription, total_free и total_subscription. Используйте значения ответа: бюджеты зависят от выбранной версии игры.
Оружейная
| Метод и путь | Назначение |
|---|---|
| POST /armory/avatars | До 100 персонажей, отсортированных по уровню и рейтингу экипировки. Ответ {"items": [...], "servers": [...]}; пагинации и total нет. |
| GET /armory/avatars/{id} | Персонаж по ID персонажа на сайте, включая экипировку и время обновления. |
POST /armory/avatars принимает необязательные search, server и class_key. search — точное имя до 256 символов без учёта регистра; е и ё различаются. server — идентификатор сервера из servers[].id, class_key — код класса (slug из /character-classes). Без фильтров отправьте {}.
В списке персонажа доступны id, name, guild, level, gear_score, class, race, faction и server. class и race — коды, а не переведённые подписи. Скрытые и удалённые персонажи и серверы не возвращаются.
Подробный ответ дополнительно содержит greatness, updated_at и equipment. В equipment у записи есть position, place и item. Для отсутствующего в базе предмета item.id равен null и unknown равен true; характеристики при этом могут присутствовать. updated_at передаёт время источника без часового смещения.
Примеры запросов
curl -X POST 'https://api.allodswiki.ru/api/v2/public/items' -H 'X-Site: allodswiki.ru' -H 'Content-Type: application/json' --data '{"page":1}'
curl -X POST 'https://api.allodswiki.ru/api/v2/public/quests' -H 'X-Site: allodswiki.ru' -H 'Content-Type: application/json' --data '{"page":1,"level_min":60,"level_max":70,"faction":"league","sort":"level","desc":true}'
curl 'https://api.allodswiki.ru/api/v2/public/character-classes' -H 'X-Site: allodswiki.ru'
curl 'https://api.allodswiki.ru/api/v2/public/talents/warrior' -H 'X-Site: allodswiki.ru'
curl -X POST 'https://api.allodswiki.ru/api/v2/public/armory/avatars' -H 'X-Site: allodswiki.ru' -H 'Content-Type: application/json' --data '{}'
Ответы и ограничения
Успешные запросы возвращают HTTP 200 и JSON без дополнительной общей обёртки. Состав подробностей и подсказок зависит от типа ресурса; подсказка является отдельным, более коротким ответом.
Для /zones/{id} возможен HTTP 200 с {"redirect_id": 123}: запрошенная подзона относится к корневой локации. Продолжите чтение по возвращённому ID.
Ошибки возвращаются как {"error": {"code": "…", "message": "…"}}. При 422 validation_failed поле error.fields содержит ошибки параметров. 404 game_resource_not_found означает недоступный ресурс, 404 armory_character_not_found — персонажа, 404 talent_layout_not_found — раскладку.
Действующий лимит запросов указан в X-RateLimit-Limit, оставшееся количество — в X-RateLimit-Remaining. При HTTP 429 too_many_requests дождитесь Retry-After; X-RateLimit-Reset содержит время сброса в Unix-секундах.