Публичный API
← Назад к оглавлению документации
Небольшой HTTP API только для чтения, позволяющий получать статус сервера извне панели: панель состояния, монитор доступности, бот для Discord, правило автоматизации для дома. Он обслуживается самой панелью и возвращает те же данные в реальном времени, которые отображают собственные страницы панели (из кэша в памяти), поэтому опрос API никогда не затрагивает Docker.
Он отключен, пока администратор не воспользуется им, и управляется администратором. Ничего не раскрывается, пока не существует токен.
Включение
Заголовок раздела «Включение»Настройки → Публичный API → Новый ключ. Присвойте ему имя, выберите, что он может видеть (все серверы или определенный поднабор) и, при желании, дату истечения срока действия. Полный ключ (токен Bearer) отображается один раз в диалоговом окне; скопируйте его сейчас, потому что впоследствии будет сохранена только короткая часть для идентификации в списке.

Создание первого ключа автоматически включает 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-адрес клиента, который в пять раз
превышает это число, поэтому попытки запросов с отсутствующими, некорректными, отозванными или
истекшими токенами не могут обойти бюджет путем их ротации.
Конечные точки
Заголовок раздела «Конечные точки»GET /api/v1/servers
Заголовок раздела «GET /api/v1/servers»Каждый сервер, к которому привязан токен.
{ "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 } } ]}GET /api/v1/servers/:id
Заголовок раздела «GET /api/v1/servers/:id»Один сервер, тот же объект под ключом 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