Документация API мониторинга

Документация API

MCListing.RU — мониторинг серверов Minecraft. Публичный API отдаёт каталог серверов, их статус и статистику античита MCLGuard в формате JSON. Ниже — все публичные эндпоинты, параметры и примеры ответов.

Начало работы

Базовый адрес всех эндпоинтов:

https://mclisting.ru

Формат ответа — всегда JSON (Content-Type: application/json; charset=utf-8).
Авторизация — не требуется, эндпоинты только на чтение.
CORS — отдаётся Access-Control-Allow-Origin: *, можно вызывать прямо из браузера.
Кэширование — каталог серверов кэшируется на 60 секунд, статистика античита — на 5 минут. Не опрашивайте чаще без необходимости.
Метод — GET.

Все URL ниже приведены относительно базового адреса. Например, /api/servers.php — это https://mclisting.ru/api/servers.php.

Публичный API мониторинга

GET /api/servers.php

Каталог серверов с фильтрами, поиском, сортировкой и пагинацией. Отдаёт тот же публичный набор данных, что виден на сайте.

Параметры запроса

Параметр	Тип		Описание
`search`	string	опц.	Поиск по названию или IP.
`version`	string	опц.	Фильтр по версии. Можно несколько через запятую: `1.20.1,1.21`.
`online`	0/1	опц.	`1` — только серверы онлайн.
`paid`	0/1	опц.	`1` — только с платным размещением (PREMIUM / TOP / VIP).
`sort`	string	опц.	`rating` (по умолчанию), `online` или `newest`.
`page`	int	опц.	Номер страницы, с 1.
`limit`	int	опц.	Размер страницы, 1–50 (по умолчанию 25).

Пример запроса

curl "https://mclisting.ru/api/servers.php?online=1&sort=online&limit=2"

Пример ответа

{
  "success": true,
  "page": 1,
  "limit": 2,
  "total": 340,
  "servers": [
    {
      "id": 123,
      "name": "Example Craft",
      "ip": "play.example.ru",
      "port": 25565,
      "address": "play.example.ru",
      "version": "1.20.1",
      "online": true,
      "players_online": 128,
      "max_players": 500,
      "rating": 4.8,
      "votes": 210,
      "page_url": "https://mclisting.ru/server/123"
    }
  ]
}

Поля объекта сервера

Поле	Тип	Описание
`id`	int	Идентификатор сервера.
`name`	string	Название.
`ip`	string	Хост/IP для подключения.
`port`	int	Порт.
`address`	string	Готовый адрес (без порта, если 25565).
`version`	string	Поддерживаемые версии.
`description`	string	Описание (до 300 символов).
`website`	string\|null	Сайт сервера.
`logo`	string\|null	Абсолютный URL логотипа.
`banner`	string\|null	Абсолютный URL баннера.
`online`	bool	Онлайн ли сейчас.
`players_online`	int	Игроков онлайн.
`max_players`	int	Слотов.
`rating`	float	Рейтинг.
`votes`	int	Число голосов.
`premium` / `top` / `vip`	bool	Флаги платного размещения.
`last_check`	string	Время последней проверки.
`page_url`	string	Ссылка на страницу сервера.

GET /api/servers.php?id={id}

Один сервер по идентификатору. Возвращает тот же объект, что в списке.

Параметры

Параметр	Тип		Описание
`id`	int	обяз.	ID сервера.

Пример

curl "https://mclisting.ru/api/servers.php?id=123"

{
  "success": true,
  "server": { "...объект сервера..." }
}

Если сервер не найден — код 404 и {"success": false, "error": "Server not found"}.

GET /api/server-status.php?id={id}

Облегчённый эндпоинт: только онлайн-статус и число игроков. Удобно для частого опроса виджетов.

Пример

curl "https://mclisting.ru/api/server-status.php?id=123"

{
  "success": true,
  "online": true,
  "players": 128,
  "max_players": 500
}

GET /api/anticheat/stats.php

Публичная агрегированная статистика античита MCLGuard. Без параметров, кэш ~5 минут.

Пример ответа

{
  "ok": true,
  "servers_protected": 42,
  "servers_total": 57,
  "violations_total": 18340,
  "violations_7d": 1204,
  "bans_players": 311,
  "cached_at": "2026-08-18T12:00:00+03:00"
}

Поле	Описание
`servers_protected`	Серверов под активной защитой (плагин недавно выходил на связь).
`servers_total`	Активных лицензий всего.
`violations_total`	Всего зафиксировано нарушений.
`violations_7d`	Нарушений за последние 7 дней.
`bans_players`	Игроков в общем бан-листе.

Плагин-античит MCLGuard

MCLGuard — серверный плагин-античит каталога. Его сетевые эндпоинты (проверка лицензии, отчёты о нарушениях, общий бан-лист) — это внутренний защищённый протокол «плагин ↔ каталог», а не публичный API, поэтому они здесь не документируются.

Как MCLGuard устроен, что он проверяет, чем отличаются тарифы FREE и PRO и что настраивается в config.yml — в отдельном руководстве:

Документация античита MCLGuard

Ошибки

При ошибке возвращается JSON с полем error и соответствующий HTTP-код, а также "success": false.

Код	Значение
`200`	Успех.
`400`	Неверные параметры запроса.
`404`	Ресурс не найден (например, сервер по id).
`500`	Внутренняя ошибка сервера.

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