Перейти к содержимому

Публичный API

← Назад к оглавлению документации

Небольшой HTTP API только для чтения, позволяющий получать статус сервера извне панели: панель состояния, монитор доступности, бот для Discord, правило автоматизации для дома. Он обслуживается самой панелью и возвращает те же данные в реальном времени, которые отображают собственные страницы панели (из кэша в памяти), поэтому опрос API никогда не затрагивает Docker.

Он отключен, пока администратор не воспользуется им, и управляется администратором. Ничего не раскрывается, пока не существует токен.

Настройки → Публичный API → Новый ключ. Присвойте ему имя, выберите, что он может видеть (все серверы или определенный поднабор) и, при желании, дату истечения срока действия. Полный ключ (токен Bearer) отображается один раз в диалоговом окне; скопируйте его сейчас, потому что впоследствии будет сохранена только короткая часть для идентификации в списке.

Настройки публичного API

Создание первого ключа автоматически включает API (переключатель Разрешить внешним приложениям читать статус является элементом управления паузой: выключите его, чтобы прекратить обслуживание, не отменяя никаких ключей). Отмените ключ из той же таблицы в любое время; клиенты, использующие его, немедленно теряют доступ.

Токены хранятся в виде хэша SHA-256 (никогда не в открытом тексте), переживают перезапуск панели и переживают серверы, для которых они были созданы (удаленный сервер просто исключается из результатов этого токена).

Отправьте токен как учетные данные Bearer:

Authorization: Bearer msm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Нет никаких файлов cookie и нет CORS: это предназначено для серверных и CLI-клиентов, а не для браузерных приложений с другого источника. Если панель находится за обратным прокси-сервером, убедитесь, что прокси пересылает заголовок Authorization.

Ошибки возвращают 401 с { "ok": false, "error": "..." }. Любой запрос, кроме GET (или HEAD), возвращает 405. Неизвестные пути возвращают 404. Когда API отключен, все маршруты возвращают 404.

Каждый токен получает свой собственный бюджет, RATE_LIMIT_PUBLIC_API_PER_MIN (по умолчанию 120 запросов в минуту; 0 отключает ограничитель). Превышение лимита возвращает 429. Каждый запрос, еще до проверки токена, также учитывается в общем лимите на IP-адрес клиента, который в пять раз превышает это число, поэтому попытки запросов с отсутствующими, некорректными, отозванными или истекшими токенами не могут обойти бюджет путем их ротации.

Каждый сервер, к которому привязан токен.

{
"ok": true,
"total": 1,
"online": 1,
"servers": [
{
"id": "srv_ab12cd34",
"name": "SMP",
"type": "PAPER",
"state": "running",
"cpuPct": 18.4,
"memoryMb": 2048,
"memoryLimitMb": 4096,
"uptimeSeconds": 11722,
"players": { "online": 3, "max": 20 }
}
]
}

Один сервер, тот же объект под ключом server. Возвращает 404 для неизвестного id и для сервера, к которому токен не привязан (нет оракула существования), и 400 для некорректного id.

Поле Значение
total Сколько серверов видно этому токену (после фильтрации по области действия).
online Сколько из них в состоянии: running.
id Стабильный id сервера (srv_...).
name Отображаемое имя.
type Тип сервера itzg (PAPER, FABRIC, AUTO_CURSEFORGE, …).
state running, starting, stopped или crashed: стабильное обобщение внутреннего состояния панели.
cpuPct Недавний % ЦП или null, когда сервер не запущен.
memoryMb Используемая память в МБ или null.
memoryLimitMb Настроенный лимит памяти контейнера в МБ или null.
uptimeSeconds Секунды с момента запуска контейнера или null.
players { online, max } или null до тех пор, пока сервер не предоставит список игроков.
Окно терминала
curl -s https://panel.example.com/api/v1/servers \
-H "Authorization: Bearer $MSM_TOKEN" | jq