Справочник REST API
HTTP API, который предоставляет демон Saba-chan. Схема аутентификации и каталог основных эндпоинтов.
Справочник REST API
Демон Saba-chan (saba-core) предоставляет HTTP REST API на 127.0.0.1:57474. GUI и CLI вызывают только этот API, а команды Discord, приходящие через облачный ретранслятор, обрабатываются теми же функциями внутри демона. По тому же контракту можно написать собственный клиент.
Этот справочник кратко описывает маршруты, которые, скорее всего, понадобятся пользователю или интегратору, по определениям маршрутов демона (src/ipc/). Некоторые внутренние маршруты опущены, а схемы полей могут меняться, поэтому актуальную информацию смотрите в коде.
1. Основы
- Базовый URL:
http://127.0.0.1:57474(по умолчанию). Можно изменить переменной окруженияSABA_IPC_PORTили параметромgui.ipcPortвconfig.json(вступает в силу после перезапуска демона). - Адрес привязки: жёстко задан как
127.0.0.1, поэтому снаружи недоступен. Запросы, у которых заголовокHostне является loopback-адресом (127.0.0.1,localhost,::1), получают 403. - Аутентификация: каждому запросу, кроме
/health, нужен заголовокX-Saba-Token. Демон создаёт новый токен при каждом запуске и записывает его в файл.ipc_tokenв папке данных (Windows:%APPDATA%\saba-chan\.ipc_token). При отсутствующем или неверном токене возвращается 401 без тела. - Content-Type: тела запросов —
application/json. Большинство ответов тоже в JSON (исключения — пакеты GUI расширений, значки и т. п.). - Формат ошибок: зависит от маршрута. Распространённые формы —
{"error": "...", "error_code": "..."},{"success": false, "error": ..., "error_code": ...}и{"ok": false, "error": ...}. Некоторые маршруты при ошибке возвращают HTTP 200 сok:false, поэтому проверяйте и тело.
2. Проверка работоспособности и демон
GET /health # токен не нужен
GET /api/version
GET /api/diagnostics
GET /api/events # поток событий (SSE)
POST /api/daemon/shutdown
/health:{"ok": true, "version": "x.y.z", "pid": 1234, "token": "valid" | "invalid" | "missing"}.tokenлишь сообщает, верен ли отправленныйX-Saba-Token; само значение никогда не раскрывается./api/version:{version, components: {...}}(версии ядра, модулей и расширений)./api/events: Server-Sent Events. Основные типы —instance.exit(завершение сервера / вердикт о сбое),backup.done,update.available,schedule.warn,provision.progressиaction.run. При переподключении пропущенные события можно догнать с помощью заголовкаLast-Event-IDили?since=<n>./api/daemon/shutdown: завершает работу демона.
3. Серверы (экземпляры)
Saba-chan управляет каждым сервером как экземпляром, который идентифицируется UUID (id).
3.1 Список, создание, изменение, удаление
GET /api/servers # список серверов + состояние работы
GET /api/instances # список экземпляров
POST /api/instances # создать
PUT /api/instances/reorder # тело: { "order": [id, ...] }
GET /api/instance/:id # подробности (+ состояние согласия с условиями в agreements)
PATCH /api/instance/:id # изменить настройки (объект ключ-значение)
DELETE /api/instance/:id # удалить
POST /api/instance/:id/rename # тело: { "name": "..." }
- Основные поля
POST /api/instances:{ "name", "module_name", "port"?, "preset"?, "module_settings"?, "accept_agreements"?: [id] }. При успехе возвращается 201{success, id, ...}, а если в модуле определён этап установки, в фоне начинается установка файлов сервера (§3.5). - Помимо порта и настроек модуля,
PATCH /api/instance/:idпринимает и настройки демона, например:auto_restart,restart_on_unknown_exit: перезапускать ли автоматически после сбоя / завершения по неизвестной причинеextra_args: дополнительные аргументы запуска (строка или массив строк;nullочищает их)memory_limit_mb: лимит памяти (МиБ, не менее 256; принимаются формы"4G"/"4096M";null/0— без ограничения). Действует только в Windows.
- Для переименования сервер должен быть остановлен; если имя уже занято, возвращается 409
name_taken.
3.2 Запуск / остановка / перезапуск
POST /api/instance/:id/start
POST /api/instance/:id/stop # необязательное тело: { "force": true }
POST /api/instance/:id/restart # необязательное тело: { "force": true }
GET /api/instance/:id/events # история последних завершений
GET /api/server/:name/status # состояние по имени
- Перед запуском демон проверяет согласие с условиями и выполняет проверки модуля. Непринятые условия возвращают 409
agreement_required(сagreements); критический провал проверки — 409preflight_failed. - Остановка отправляет игре команду корректной остановки, ждёт тайм-аут модуля (по умолчанию 30 секунд) и принудительно завершает процесс, если он ещё жив. С
force: trueпроцесс завершается немедленно. eventsвозвращает{events: [...]}с вердиктом о завершении (user_stop,in_game_stop,crash,unknown_exit), доказательствами, запланированным автоперезапуском и т. д.
3.3 Консоль и команды
GET /api/instance/:id/console?since=<id>&count=<n>
POST /api/instance/:id/stdin # тело: { "command": "say hello" }
POST /api/instance/:id/command # тело: { "command": "<name>", "args"?: {...} }
GET /api/instance/:id/commands # команды, доступные для этого сервера
POST /api/instance/:id/rest # игры только с REST (например, Palworld)
POST /api/instance/:id/rcon # имя для совместимости; использует путь команд ниже (stdin → REST → RCON)
- Опрос консоли: ответ —
{success, lines: [{id, timestamp, source, content, level}], running, ...}. Сsinceвозвращаются строки, у которыхidбольше или равен ему, поэтому в следующий раз отправляйте последний полученныйid+ 1. Безsinceвы получите последниеcountстрок (по умолчанию 100). Демон хранит в памяти последние 10 000 строк каждого сервера. - Порядок путей команд: stdin → REST → RCON. Команды сначала идут в консоль сервера (stdin), а для игр, поддерживающих только REST, например Palworld, — через REST. RCON используется только для игры, модуль которой объявляет
supported = ["rcon"](нет ни консоли, ни REST API); тогда демон назначает каждому экземпляру свой порт и случайный пароль и подключается только через loopback (127.0.0.1). В остальных случаях/rcon— путь, сохранённый только по имени для старых клиентов; он отправляет в stdin. Серверы без пути команд возвращают 409no_command_path. /stdinвозвращает 409stdin_not_supported, если модуль не поддерживает stdin./commandвыполняет команду, определённую модулем; если сервер остановлен, возвращается 409server_not_running.
3.4 Настройки, условия, проверки
POST /api/instance/:id/launch-preview # тело: { "settings"?: {...}, "extra_args"?: "..." }
POST /api/instance/:id/agreements # тело: { "accept": ["eula"] }
GET /api/instance/:id/properties # прочитать конфигурационный файл игры
PUT /api/instance/:id/properties # тело: { "settings": {...} }
POST /api/instance/:id/validate # проверка сервера
POST /api/instance/:id/diagnose # диагностика журнала
launch-previewвычисляет командную строку запуска, не запуская сервер. Пример ответа:{success: true, has_launch_args, command_line, program, args, extra_args, errors: [...]}. Значения паролей маскируются как***. Если модуль не объявляет аргументов запуска, возвращаетсяhas_launch_args: false.agreementsзаписывает согласие с условиями, которые объявляет модуль (например,eulaв Minecraft). Работает только локально; запросы из удалённых источников (Discord и т. п.) получают 403agreement_local_only. Для необъявленных id возвращается 400invalid_format.
3.5 Ход установки и обновления игрового сервера
GET /api/provision-progress/:name # :name = имя экземпляра
DELETE /api/provision-progress/:name # закрыть состояние неудачного прогресса
GET /api/instance/:id/check-update
POST /api/instance/:id/apply-update
Пример ответа provision-progress:
{
"active": true,
"step": 2,
"total": 5,
"label": "...",
"message": "...",
"percent": 40,
"done": false,
"error": null
}
Когда ничего не выполняется, возвращается {"active": false}. Успешное состояние прогресса автоматически очищается через 5 секунд; неудачное остаётся, пока вы не закроете его через DELETE (если сервер только создавался, в этот момент создание откатывается). Прогресс доступен и как provision.progress в /api/events.
apply-update возвращает 409 server_running, если сервер работает. Перед обновлением делается бэкап (для модулей с поддержкой бэкапов).
3.6 Бэкапы и задачи по расписанию
GET /api/instance/:id/backups # { success, backups: [{ name, kind, created, size }] }
POST /api/instance/:id/backups # сделать бэкап сейчас
DELETE /api/instance/:id/backups/:name
POST /api/instance/:id/backups/:name/restore # сервер должен быть остановлен
GET /api/instance/:id/schedule
PUT /api/instance/:id/schedule # тело: { "schedule": [...], "backup_keep"?: 10 }
kindбэкапа:manual,scheduled,pre-update,pre-restore. Если модуль не поддерживает бэкапы, возвращается 400backup_unsupported; если сохранять пока нечего — 400nothing_to_back_up.- Восстановление возвращает 409
server_running, если сервер работает, а перед восстановлением текущее состояние сохраняется какpre-restore. - Вид одной задачи по расписанию:
{ "action": "restart", "at": "05:00", "warn_minutes": [10, 5, 1], "enabled": true }
action — backup | restart | announce | update; используется ровно одно из every_minutes (каждые N минут) и at (ежедневно в HH:MM). Для announce нужен message, а warn_minutes применяется только к restart и update. Неверные задачи возвращают 400 validation_failed (с details).
4. Модули
GET /api/modules # установленные модули
POST /api/modules/refresh # перечитать папку модулей
GET /api/module/:name # метаданные модуля
GET /api/module/:name/versions # версии игрового сервера, доступные для установки
GET /api/module/:name/locales
GET /api/modules/manifest # каталог модулей, доступных для установки
POST /api/modules/manifest/:id/install # установить модуль из каталога
DELETE /api/modules/:id # удалить модуль
Каталог модулей берётся из подписанного списка релизов, а загруженные файлы устанавливаются только после сверки их хеша.
5. Расширения
GET /api/extensions # список с состоянием установки/включения
POST /api/extensions/rescan
GET /api/extensions/manifest # каталог расширений, доступных для установки
GET /api/extensions/updates
POST /api/extensions/:id/install
DELETE /api/extensions/:id
POST /api/extensions/:id/enable # асинхронно выполняет хук daemon.startup
POST /api/extensions/:id/disable
GET /api/extensions/:id/config
PUT /api/extensions/:id/config
GET /api/extensions/:id/gui # пакет GUI (UMD JavaScript)
GET /api/extensions/:id/gui/styles # CSS
GET /api/extensions/:id/i18n/:locale # ko / en / ja / ...
Ошибки маршрутов расширений имеют вид {success: false, error, error_code, ...}.
6. Настройки
GET /api/config/gui
PUT /api/config/gui # частичный JSON (поверхностное слияние)
GET /api/config/bot
PUT /api/config/bot # настройки бота, например префикс и псевдонимы (частичный JSON)
GET /api/system/metrics # CPU, память, диск, потребление по серверам
Все пользовательские настройки хранятся по пространствам имён в одном файле config.json в папке данных. Демон синхронизирует настройки бота с ретранслятором. Сам Discord-бот работает на облачном ретрансляторе, поэтому у демона нет API для запуска или остановки процесса бота.
7. Обновления
GET /api/updates/status # текущее состояние и версии по компонентам
POST /api/updates/check # проверить обновления сейчас
POST /api/updates/download # необязательное тело: { "components": [...] }
GET /api/updates/download/progress
POST /api/updates/apply # необязательное тело: { "components": [...] }
POST /api/updates/launch-updater # применить через установщик (демон останавливается)
GET /api/updates/config
PUT /api/updates/config
Сведения об обновлениях берутся из подписанного списка релизов. Компоненты, чьи работающие файлы нужно заменить, помечаются в ответе apply как требующие отдельного применения; вызов launch-updater запускает установщик (saba-chan-installer --apply), который останавливает демон, заменяет файлы и снова запускает только то, что изменилось. Эти маршруты отвечают в виде {ok: ...}.
8. Сопряжение с облачным ретранслятором
Для процесса сопряжения GUI ↔ сервер-ретранслятор. Подробный порядок действий — на странице Discord-бот.
POST /api/relay/pair/initiate # выдать код сопряжения (передаётся ретранслятору)
GET /api/relay/pair/:code/status # опросить, завершено ли сопряжение
GET /api/relay/agent # состояние агента ретранслятора
POST /api/relay/agent/start
POST /api/relay/agent/stop
DELETE /api/config/node-token # удалить токен узла этого ПК (останавливает агента)
Когда сопряжение завершено (status: "claimed"), демон автоматически сохраняет токен узла и переподключает агента ретранслятора с новым токеном. Аутентификацией перед ретранслятором занимается демон, так что клиентам об этом заботиться не нужно.
9. Пример аутентификации (curl)
TOKEN=$(cat "$APPDATA/saba-chan/.ipc_token")
curl -H "X-Saba-Token: $TOKEN" \
http://127.0.0.1:57474/api/servers
curl -X POST \
-H "X-Saba-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"command":"list"}' \
http://127.0.0.1:57474/api/instance/<instance-id>/stdin
<instance-id> — это id из ответа GET /api/servers или GET /api/instances.
10. Совместимость версий
- Этот API относится к приватному IPC. Это не публичный контракт, поэтому пути и схемы могут меняться даже в минорных версиях.
- Если вы распространяете собственный клиент, проверяйте версию демона (
versionизGET /health) и обрабатывайте её консервативно.
Если возникли проблемы, переходите в раздел Устранение неполадок.