公開API
パネル外からサーバーのステータスを取得するための、小さく読み取り専用のHTTP APIです。ステータスダッシュボード、アップタイムモニター、Discordボット、ホームオートメーションルールなどに利用できます。これはパネル自体によって提供され、パネルのページが表示するのと同じライブデータ(インメモリキャッシュから)を返します。そのため、ポーリングしてもDockerにアクセスすることはありません。
これは管理者が使用するまで無効であり、管理者によって保護されています。トークンが存在しない限り、何も公開されません。
設定 → パブリックAPI → 新規キー。名前を付け、表示するサーバー(全サーバー、または特定のサブセット)を選択し、オプションで有効期限を設定します。完全なキー(Bearerトークン)は、ダイアログで一度だけ表示されます。後で識別するために短いプレフィックスしか保持されないため、今すぐコピーしてください。

最初のキーを作成すると、APIは自動的にオンになります(外部アプリにステータスの読み取りを許可するスイッチは一時停止コントロールです。キーをキャンセルせずに、提供を停止するにはオフにします)。いつでも同じテーブルからキーをキャンセルできます。それを使用しているクライアントは、すぐにアクセスできなくなります。
トークンはSHA-256ハッシュとして保存され(平文では決して保存されません)、パネルの再起動後も保持され、スコープが設定されたサーバーよりも長く存続します(削除されたサーバーは、そのトークンの結果から単純に除外されます)。
トークンをBearer認証情報として送信します。
Authorization: Bearer msm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxCookieはなく、CORSもありません。これはサーバー間通信やCLIからの呼び出し用であり、他のオリジンのブラウザアプリ用ではありません。パネルがリバースプロキシの背後にある場合は、プロキシがAuthorizationヘッダーを転送するようにしてください。
エラーは401と{ "ok": false, "error": "..." }を返します。GET(またはHEAD)以外のメソッドは405を返します。パスが見つからない場合は404を返します。APIが無効な場合、すべてのルートが404を返します。
各トークンには独自の予算があります。RATE_LIMIT_PUBLIC_API_PER_MIN(デフォルトは120リクエスト/分、0はリミッターを無効にします)。制限を超えると429を返します。各リクエストは、トークンがチェックされる前に、クライアントIPごとの上限(その数値の5倍)にもカウントされます。そのため、存在しない、不正な形式の、取り消された、または期限切れのトークンを使用してプローブしても、ローテーションによって予算を回避することはできません。
エンドポイント
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”1つのサーバー。serverキーの下に同じオブジェクトが返されます。不明なIDおよびトークンがスコープされていないサーバー(存在しない場合)に対しては404を返します。不正な形式のIDに対しては400を返します。
レスポンスフィールド
Section titled “レスポンスフィールド”| フィールド | 説明 |
|---|---|
total |
このトークンから見えるサーバーの数(スコープフィルター適用後)。 |
online |
そのうちrunning状態のサーバーの数。 |
id |
安定したサーバーID(srv_...)。 |
name |
表示名。 |
type |
itzgサーバータイプ(PAPER、FABRIC、AUTO_CURSEFORGEなど)。 |
state |
running、starting、stopped、またはcrashed:パネルの内部状態の安定した概要。 |
cpuPct |
最近のCPU使用率(%)、またはサーバーが実行されていない場合はnull。 |
memoryMb |
メモリ使用量(MB)、またはnull。 |
memoryLimitMb |
設定されたコンテナメモリ制限(MB)、またはnull。 |
uptimeSeconds |
コンテナ起動からの経過秒数、またはnull。 |
players |
{ online, max }、またはサーバーがプレイヤーリストを報告するまでnull。 |
curl -s https://panel.example.com/api/v1/servers \ -H "Authorization: Bearer $MSM_TOKEN" | jq