Публічний API
← Назад до індексу документації
Невеликий HTTP API лише для читання для отримання статусу сервера ззовні панелі: інформаційна панель статусу, монітор часу роботи, бот Discord, правило домашньої автоматизації. Він обслуговується самою панеллю та повертає ті самі дані в реальному часі, які показують власні сторінки панелі (з кешу в пам’яті), тому опитування його ніколи не торкається Docker.
Він вимкнений, доки адміністратор його не використає, і контролюється адміністратором. Нічого не відображається, доки не існує токен.
Увімкнення
Section titled “Увімкнення”Налаштування → Публічний API → Новий ключ. Надайте йому назву, виберіть, що він може бачити (усі сервери або певний підмножина) та, за бажанням, дату закінчення терміну дії. Повний ключ (токен Bearer) відображається один раз у діалоговому вікні; скопіюйте його зараз, оскільки пізніше зберігається лише коротка префікс для ідентифікації у списку.

Створення першого ключа автоматично вмикає API (перемикач Дозволити зовнішнім програмам читати статус є елементом керування паузою: вимкніть його, щоб припинити обслуговування без скасування будь-яких ключів). Скасуйте ключ з тієї ж таблиці в будь-який час; клієнти, які його використовують, негайно втрачають доступ.
Токени зберігаються як хеш SHA-256 (ніколи у відкритому тексті), переживають перезапуск панелі та переживають сервери, до яких вони прив’язані (видалений сервер просто випадає з результатів цього токена).
Автентифікація
Section titled “Автентифікація”Надішліть токен як облікові дані Bearer:
Authorization: Bearer msm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxНемає файлів cookie та немає CORS: це для взаємодії сервер-сервер та викликів CLI,
а не для браузерних програм з іншого джерела. Якщо панель знаходиться за зворотним проксі, переконайтеся, що проксі пересилає заголовок Authorization.
Помилки повертають 401 з { "ok": false, "error": "..." }. Будь-що, крім GET
(або HEAD), повертає 405. Невідомі шляхи повертають 404. Коли API вимкнено, кожен маршрут
повертає 404.
Обмеження швидкості
Section titled “Обмеження швидкості”Кожен токен отримує власний бюджет, RATE_LIMIT_PUBLIC_API_PER_MIN (за замовчуванням 120
запитів/хвилину; 0 вимикає обмежувач). Перевищення ліміту повертає 429. Кожен запит, ще до перевірки його токена, також враховується в загальному ліміті на IP-адресу клієнта, що вп’ятеро перевищує це число, тому перевірка з відсутніми, неправильно сформованими, відкликаними або простроченими токенами не може обійти бюджет, обертаючи їх.
Кінцеві точки
Section titled “Кінцеві точки”GET /api/v1/servers
Section titled “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
Section titled “GET /api/v1/servers/:id”Один сервер, той самий об’єкт під ключем server. Повертає 404 для невідомого id
та для сервера, до якого токен не прив’язаний (немає оракула існування), і 400
для неправильно сформованого id.
Поля відповіді
Section titled “Поля відповіді”| Поле | Значення |
|---|---|
total |
Скільки серверів видимі для цього токена (після фільтра його області видимості). |
online |
Скільки з них у стані: running. |
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, доки сервер не надасть список гравців. |
Приклад
Section titled “Приклад”curl -s https://panel.example.com/api/v1/servers \ -H "Authorization: Bearer $MSM_TOKEN" | jq