REST API リファレンス
サバちゃんデーモンが公開する HTTP API。認証方式と主要なエンドポイントのカタログ。
REST API リファレンス
サバちゃんのデーモン(saba-core)は、127.0.0.1:57474 で HTTP REST API を公開しています。GUI と CLI はこの API だけを呼び出し、クラウドリレー経由で届く Discord のコマンドも、デーモン内の同じ機能で処理されます。同じ契約に沿って独自のクライアントを作ることもできます。
このリファレンスは、デーモンのルート定義(src/ipc/)から、ユーザーや連携する開発者が必要としそうなルートをまとめたものです。一部の内部ルートは省略しています。フィールドのスキーマは変わることがあるため、最新の情報はコードを参照してください。
1. 基本
- ベース URL:
http://127.0.0.1:57474(既定)。SABA_IPC_PORT環境変数、またはconfig.jsonのgui.ipcPortで変更できます(デーモンの再起動後に反映)。 - バインドアドレス:
127.0.0.1に固定されているため、外部からはアクセスできません。Hostヘッダーがループバック(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. サーバー(インスタンス)
サバちゃんは各サーバーを インスタンス として管理し、UUID(id)で識別します。
3.1 一覧、作成、更新、削除
GET /api/servers # サーバー一覧 + 実行状態
GET /api/instances # インスタンス一覧
POST /api/instances # 作成
PUT /api/instances/reorder # body: { "order": [id, ...] }
GET /api/instance/:id # 詳細 (+ agreements に規約への同意状態)
PATCH /api/instance/:id # 設定の変更 (キーと値のオブジェクト)
DELETE /api/instance/:id # 削除
POST /api/instance/:id/rename # body: { "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:メモリ上限(MiB、256 以上。"4G"/"4096M"の形式も可。null/0は無制限)。Windows でのみ適用されます。
- 名前の変更にはサーバーの停止が必要です。すでに使われている名前には 409
name_takenが返ります。
3.2 起動 / 停止 / 再起動
POST /api/instance/:id/start
POST /api/instance/:id/stop # 任意の body: { "force": true }
POST /api/instance/:id/restart # 任意の body: { "force": true }
GET /api/instance/:id/events # 最近の終了履歴
GET /api/server/:name/status # 名前による状態
- 起動の前に、デーモンは規約への同意を確認し、モジュールのチェックを実行します。未同意の規約がある場合は 409
agreement_required(agreements付き)、重大なチェックの失敗は 409preflight_failedが返ります。 - 停止では、ゲームの正常停止コマンドを送り、モジュールのタイムアウト(既定 30秒)まで待ち、プロセスがまだ生きていれば強制終了します。
force: trueなら直ちに終了させます。 eventsは、終了の判定(user_stop、in_game_stop、crash、unknown_exit)、その根拠、予定された自動再起動などを含む{events: [...]}を返します。
3.3 コンソールとコマンド
GET /api/instance/:id/console?since=<id>&count=<n>
POST /api/instance/:id/stdin # body: { "command": "say hello" }
POST /api/instance/:id/command # body: { "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)に送られ、Palworld のように REST にしか対応していないゲームは REST を経由します。RCON はモジュールが
supported = ["rcon"]と宣言したゲーム(コンソールも REST API もないゲーム)でのみ使われ、その場合デーモンがインスタンスごとにポートとランダムなパスワードを割り当て、ループバック(127.0.0.1)でのみ接続します。それ以外の場合、/rconは古いクライアントのために名前だけ残しているパスで、stdin に送ります。コマンド経路のないサーバーでは 409no_command_pathが返ります。 /stdinは、モジュールが stdin に対応していなければ 409stdin_not_supportedを返します。/commandはモジュールが定義したコマンドを実行します。サーバーが停止していれば 409server_not_runningを返します。
3.4 設定、規約、チェック
POST /api/instance/:id/launch-preview # body: { "settings"?: {...}, "extra_args"?: "..." }
POST /api/instance/:id/agreements # body: { "accept": ["eula"] }
GET /api/instance/:id/properties # ゲームの設定ファイルを読む
PUT /api/instance/:id/properties # body: { "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は、モジュールが宣言した規約(例:Minecraft のeula)への同意を記録します。ローカルでのみ 動作し、リモート(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 で閉じるまで残ります(サーバーを新規作成していた場合は、その時点でロールバックされます)。進行状況は /api/events の provision.progress でも取得できます。
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 # body: { "schedule": [...], "backup_keep"?: 10 }
- バックアップの
kind:manual、scheduled、pre-update、pre-restore。モジュールがバックアップに対応していなければ 400backup_unsupported、まだバックアップする対象がなければ 400nothing_to_back_upが返ります。 - 復元は、サーバーが動いていれば 409
server_runningを返し、復元の前に現在の状態をpre-restoreとしてバックアップします。 - 予約タスク1件の形:
{ "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、メモリ、ディスク、サーバーごとの使用量
すべてのユーザー設定は、データフォルダーにある1つの config.json ファイルに名前空間ごとに保存されます。デーモンはボットの設定をリレーに同期します。Discord ボット自体はクラウドリレー上で動作するため、デーモンにはボットのプロセスを起動・停止する API はありません。
7. アップデート
GET /api/updates/status # 現在の状態とコンポーネントごとのバージョン
POST /api/updates/check # 今すぐアップデートを確認
POST /api/updates/download # 任意の body: { "components": [...] }
GET /api/updates/download/progress
POST /api/updates/apply # 任意の body: { "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 Bot のページを参照してください。
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 # この PC のノードトークンを削除 (エージェントを停止)
ペアリングが完了すると(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> は、GET /api/servers または GET /api/instances の応答にある id です。
10. バージョンの互換性
- この API は 非公開の IPC に分類されます。公開された契約ではないため、マイナーバージョンでもパスやスキーマが変わることがあります。
- 独自のクライアントを配布する場合は、デーモンのバージョン(
GET /healthのversion)を確認し、慎重に扱ってください。
問題があれば トラブルシューティング へ。