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 付き)、重大なチェックの失敗は 409 preflight_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 に送ります。コマンド経路のないサーバーでは 409 no_command_path が返ります。
  • /stdin は、モジュールが stdin に対応していなければ 409 stdin_not_supported を返します。
  • /command はモジュールが定義したコマンドを実行します。サーバーが停止していれば 409 server_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 など)からのリクエストには 403 agreement_local_only が返ります。宣言されていない id には 400 invalid_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。モジュールがバックアップに対応していなければ 400 backup_unsupported、まだバックアップする対象がなければ 400 nothing_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)を確認し、慎重に扱ってください。

問題があれば トラブルシューティング へ。