Обзор

Integration API — HTTP API, которое ваш сайт, панель или бот вызывает со своего сервера. Каждый запрос выполняется от имени вашего проекта с его API key.

Что доступно

Сервис	Что можно делать	Scope
l2nx.top	Читать ленту голосов, искать голоса по `ref`	`top.votes:read`
Game data	Читать шаблоны предметов ваших игровых серверов	`gamedata.item-templates:read`
Промокоды	Активировать промокоды для игроков, например из личного кабинета	`gameservers.promo:redeem`

Справочные страницы каждого сервиса генерируются из его описания OpenAPI и перечислены в разделе Integration API в боковом меню. Они обновляются автоматически с каждым релизом сервиса. Справка — на английском.

Хосты и пути

Каждый сервис отдаёт API под своим префиксом:

https://{host}/{service}/v{N}/integration/...

Сервис	Хост	Пример
l2nx.top	`https://api.l2nx.top`	`https://api.l2nx.top/top/v1/integration/votes`
API проекта	`https://{tenant}.api.l2nx.app`	`https://myproject.api.l2nx.app/gamedata/v1/integration/item-templates`

На хосте проекта {tenant} — slug вашего проекта. Проект определяется по API key: ключ работает только на хосте своего проекта, ключ другого проекта получает 403 API_KEY_TENANT_MISMATCH.

Некоторым эндпоинтам нужны дополнительные заголовки, например id игрового сервера для game data. Справочная страница каждой операции их перечисляет.

Версии

Мажорная версия — часть пути (/v1/). Внутри версии изменения обратно совместимы: новые эндпоинты, новые необязательные параметры, новые поля в ответах. Незнакомые поля ответа игнорируйте. Ломающее изменение выходит под новой версией пути.

Запросы и ответы

JSON в обе стороны, UTF-8, Content-Type: application/json у запросов с телом.
Время — ISO 8601 в UTC (2026-10-12T09:33:20Z), id — UUID.
Поле без значения — null, никогда не пустая строка.

Пагинация

Списки разбиваются на страницы одним из двух способов; в справке указано, каким пользуется эндпоинт.

Ленты с курсором: after (id последнего полученного элемента) и limit. Пустая страница — конец ленты; продолжайте позже с того же курсора. Пример: лента голосов l2nx.top, limit от 1 до 500, по умолчанию 100.
Страницы: page (с 0) и size. Пример: шаблоны предметов game data, size до 50. Больший size молча уменьшается до максимума, поэтому опирайтесь на метаданные страницы в ответе, а не на запрошенный размер.

Ошибки

Ошибки следуют RFC 9457 и возвращаются как application/problem+json:

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "API key lacks a required scope",
  "code": "INSUFFICIENT_SCOPE",
  "traceId": "4f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c"
}

Поле	Смысл
`status`	HTTP-статус, совпадает со статусом ответа.
`detail`	Пояснение для человека. Не разбирайте его: текст может меняться.
`code`	Машиночитаемая причина в `UPPER_SNAKE_CASE`, например `VALIDATION_FAILED`. Ветвитесь по нему. Есть не у каждой ошибки.
`traceId`	Id запроса. Укажите его, когда пишете в поддержку.

Частые статусы:

Статус	Когда
`400`	Неверные параметры или тело.
`401`	API key нет или он невалиден. См. Аутентификация.
`403`	Ключ известен, но не допущен: отозван, просрочен, нет scope, другой проект, проект отключён.
`404`	Ресурса нет или он не принадлежит вашему проекту.
`429`	Превышен rate limit, см. ниже.
`5xx`	Сбой на стороне сервера. Повторите с нарастающей задержкой.

Rate limits

Запросы ограничиваются по API key и по scope. Если в справке эндпоинта не сказано иное, ключ может отправить до 30 запросов подряд, запас восстанавливается со скоростью 60 запросов в минуту.

При превышении API отвечает 429 с кодом RATE_LIMITED и заголовком Retry-After — числом секунд до следующего запроса. Подождите не меньше; не повторяйте запрос в плотном цикле.

HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/problem+json

{"type":"about:blank","title":"Too Many Requests","status":429,"detail":"Too many requests","code":"RATE_LIMITED","traceId":"4f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c"}

Нужен лимит выше для обоснованного сценария? Напишите в поддержку.