Публичное API

Те же данные, что показывает сайт - бои за зоны со скорбордами, матчи арены, профили семей и игроков, рейтинги и турнирные сетки, - доступны машинам по ключу. Ключ выпускается здесь же, за минуту, без заявок и переписки.

v1 стабильная версия22 ручки200 запросов в суткиJSON · UTF-8 · только GET

базовый адрес

$ curl -s \
    -H "Authorization: Bearer mh_…" \
    https://api.maj-hltv.ru/v1/overview

{
  "totalFamilies": 3514,
  "totalPlayers": 341671,
  "totalCaptures": 111559,
  "totalArenaMatches": 2462490,
  "lastCapture": "2026-10-11T21:54:00Z",
  "servers": […]
}

Быстрый старт

Три шага: войти через Discord, выпустить ключ в карточке выше, подставить его в заголовок.

bash

$ curl -H "Authorization: Bearer ВАШ_КЛЮЧ" \
    "https://api.maj-hltv.ru/v1/captures?server=RU19&limit=5"

Ответ - обычный JSON, та же форма, что уходит на страницы сайта. Ничего специально «апишного» разбирать не нужно.

Ключ в запросе

Любым из трёх способов, в этом порядке предпочтения:

Authorization: Bearer ВАШ_КЛЮЧ - основной;
X-API-Key: ВАШ_КЛЮЧ - если удобнее отдельный заголовок;
?key=ВАШ_КЛЮЧ в адресе - для быстрой проверки в браузере. Адрес целиком попадает в журналы прокси и в историю браузера, поэтому для постоянной работы берите заголовок.

Оглавление в машинном виде - GET https://api.maj-hltv.ru/v1, оно отвечает и без ключа.

Лимиты

200 запросов в сутки на ключ. Сутки календарные по UTC: счётчик обнуляется в полночь, а не через 24 часа после первого запроса. Остаток приходит в заголовках каждого ответа.

заголовки ответа

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 183
X-RateLimit-Reset: 1791849600   # время обнуления, секунды Unix

Один ключ - один адрес. Ключ рассчитан на одного потребителя: если с одного адреса приходят два разных ключа или один ключ приходит с двух адресов, второй получает 403 key_ip_conflict. Первый при этом работает как ни в чём не бывало. Ограничение ничего не запоминает и снимается само, как только прежняя пара замолкает на десять минут - то есть переезд на другой сервер или смена адреса у провайдера лечится паузой, а не обращением к нам.

Нужен лимит больше, доступ с нескольких адресов или своя схема - напишите https://t.me/gxdlxsss . Это не формальность: лимиты поднимаются по просьбе, если понятно, подо что.

Ручки

Параметры server, page, limit, sort и q работают там же и так же, как на сайте: страница списка и ответ API строятся одним и тем же кодом.

GET/v1/overview

Сводные счётчики по всем серверам: сколько семей, игроков, боёв и матчей арены.

GET/v1/captures

Лента боёв за зоны, новые сверху.

?server=RU19&limit=20&page=1

GET/v1/captures/{server}/{id}

Один бой: обе стороны, скорборд, карта, время начала и конца.

GET/v1/families

Список семей с рейтингом и основными показателями.

?server=RU19&sort=rating&q=cortez&limit=50

GET/v1/families/{server}/{id}

Профиль семьи: состав, история боёв, рейтинг.

GET/v1/families/{server}/{id}/maps

Карты семьи: где воюет и с каким успехом.

GET/v1/players

Список игроков.

?server=RU19&sort=rating&q=makito&limit=50

GET/v1/players/{server}/{id}

Профиль игрока по Static ID.

?history=100

GET/v1/arena

Лента матчей арены.

?server=RU19&limit=20

GET/v1/arena/{server}/{id}

Один матч арены.

GET/v1/rating

Официальный рейтинг организаций - тот, что считает сам игровой сервер.

?server=RU19

GET/v1/top/families

Топ семей по рейтингу сайта.

?server=RU19

GET/v1/top/players

Топ игроков по рейтингу сайта.

?server=RU19

GET/v1/mansion-transfersобязательно: server

Переходы особняков между семьями.

?server=RU19

GET/v1/servers/maps

Справочник зон: идентификатор карты и её название.

?server=RU19

GET/v1/servers/buildingsобязательно: server, kind - mansions, multipurpose или zones

Здания с текущими владельцами, включая свободные.

?server=RU19&kind=mansions

GET/v1/searchобязательно: q, от двух символов

Поиск по семьям и игрокам.

?q=cortez

GET/v1/tournaments

Список завершённых турниров.

GET/v1/tournaments/{slug}

Турнир, подиум и очки участников.

GET/v1/tournaments/{slug}/bracket

Сетка квалификаций по дням и группам.

GET/v1/tournaments/family/{server}/{id}

Турнирная история семьи.

GET/v1/tournaments/player/{server}/{id}

Турнирная история игрока.

Одно уточнение, на котором спотыкаются первым делом: идущие квалификации живут только под /tournaments/{slug}/bracket. В /tournaments турнир попадает, когда закончится, так что /tournaments/majestic-champions-cup-2 сейчас ответит 404, а его /bracket - нет.

Ошибки

Ошибка всегда приходит одним и тем же объектом, разбирать русский текст не нужно:

пример отказа

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Суточный лимит исчерпан (200 запросов)…",
    "docs": "https://maj-hltv.ru/api"
  }
}

401api_key_requiredКлюча в запросе нет вовсе.

401api_key_invalidТакого ключа не существует - возможно, он отозван и выпущен заново.

401api_key_revokedКлюч отозван владельцем.

403key_ip_conflictНарушено правило «один ключ - один адрес», см. раздел про лимиты.

429rate_limit_exceededСуточный лимит исчерпан. Когда обнулится - в заголовке X-RateLimit-Reset.

404not_foundТакой семьи, игрока, боя или ручки нет.

400bad_requestНе хватает обязательного параметра или он неверен.

500internal_errorОшибка на нашей стороне. Повторяется - напишите в Telegram.

Стабильность

Версия в адресе - /v1. Новые поля в ответах могут появляться в любой момент, поэтому разбирайте JSON по именам полей и не падайте на незнакомых. Удаление полей или смена их смысла - только со сменой версии; о такой смене я напишу в Discord заранее.

Данные предоставляются «как есть»: игровое API иногда задерживает или теряет события, и статистика наследует эти пробелы. Подробнее - в методологии.

Публичное API

Быстрый старт

Ключ в запросе

Лимиты

Ручки

Ошибки

Правила использования

Стабильность