API リファレンス
HTTP エンドポイントと WebSocket プロトコル
認証
ヘルスチェックと共有ビューを除くすべての API エンドポイントはセッション認証が必要です。
POST /api/auth/login
Content-Type: application/json
{ "password": "your-password" }共有ビュー（公開・トークンスコープ）
セッションなしで到達できるのは、以下の共有ルート（と /api/health）のみです。
共有トークンは単一トポロジー、あるいはダッシュボードの場合はそのウィジェットが
参照するトポロジー/データソース id だけへの読み取り専用アクセスを与えます。
レスポンスは公開用の形に投影され、内部フィールド（リソース自身の共有トークン、
データソース id、ホストマッピング、ポートエイリアス、タイムスタンプ）は返しません。
| Method | Endpoint | 説明 |
|---|---|---|
| GET | /api/share/topologies/:token | 共有トポロジーのコンテキスト（ノード/エッジ/メトリクス） |
| GET | /api/share/topologies/:token/graph | 共有トポロジーの NetworkGraph |
| GET | /api/share/topologies/:token/render | 共有トポロジーのレンダリング出力 |
| GET | /api/share/dashboards/:token | 共有ダッシュボードのガワ（レイアウト） |
| GET | /api/share/dashboards/:token/topologies/:id | このダッシュボード内ウィジェット用のトポロジーメタデータ |
| GET | /api/share/dashboards/:token/topologies/:id/graph | このダッシュボード内ウィジェット用の NetworkGraph |
| GET | /api/share/dashboards/:token/topologies/:id/context | デバイスステータスウィジェット用のコンテキスト |
| GET | /api/share/dashboards/:token/datasources/:id/alerts | アラートウィジェット用のアラート |
ダッシュボードのレイアウトが参照していない :id へのトークンスコープ要求は
404 を返すため、トークンで無関係なリソースを列挙することはできません。
以下の管理エンドポイント（/api/topologies/:id、/api/dashboards/:id、
/api/datasources/:id/alerts など）は常に認証が必要です。
HTTP エンドポイント
データソース
| メソッド | エンドポイント | 説明 |
|---|---|---|
| GET | /api/datasources | データソース一覧 |
| POST | /api/datasources | データソース作成 |
| GET | /api/datasources/:id | データソース詳細 |
| PUT | /api/datasources/:id | データソース更新 |
| DELETE | /api/datasources/:id | データソース削除 |
| POST | /api/datasources/:id/test | 接続テスト |
| GET | /api/datasources/:id/hosts | 監視ホスト一覧 |
| GET | /api/datasources/:id/hosts/:hostId/items | ホストのメトリクスアイテム |
| GET | /api/datasources/:id/alerts | アラート取得 |
トポロジー
| メソッド | エンドポイント | 説明 |
|---|---|---|
| GET | /api/topologies | トポロジー一覧 |
| POST | /api/topologies | トポロジー作成 |
| GET | /api/topologies/:id | トポロジー詳細 |
| PUT | /api/topologies/:id | トポロジー更新 |
| DELETE | /api/topologies/:id | トポロジー削除 |
| GET | /api/topologies/:id/render | レンダリングされたレイアウトデータ |
| GET | /api/topologies/:id/sources | 紐付けデータソース一覧 |
| POST | /api/topologies/:id/sources | データソースを紐付け |
ダッシュボード
| メソッド | エンドポイント | 説明 |
|---|---|---|
| GET | /api/dashboards | ダッシュボード一覧 |
| POST | /api/dashboards | ダッシュボード作成 |
| GET | /api/dashboards/:id | ダッシュボード詳細 |
| PUT | /api/dashboards/:id | ダッシュボード更新 |
| DELETE | /api/dashboards/:id | ダッシュボード削除 |
プラグイン
| メソッド | エンドポイント | 説明 |
|---|---|---|
| GET | /api/plugins | プラグイン一覧 |
| POST | /api/plugins | プラグイン追加（URL/パス/アップロード） |
| DELETE | /api/plugins/:id | プラグイン削除 |
Webhook
Webhook エンドポイントはセッション認証を使いません。代わりに、ソースに設定した
Webhook シークレットを X-Webhook-Secret ヘッダー（推奨）または ?secret=
クエリパラメータで送ります。シークレットは定数時間で比較され、シークレット未指定は
401、宛先不明は 404、シークレット不一致は 401 を返します。
一般形は POST /api/webhooks/:type/:id で、:id はソースの id（設定画面に
表示されるもので、シークレットではありません）。type=topology は Webhook モードの
トポロジーソースのグラフを再取得し、それ以外の type は対応するデータソースプラグインに
ディスパッチされます — 現在 Webhook を処理するのは grafana のみです。
| メソッド | エンドポイント | 説明 |
|---|---|---|
| POST | /api/webhooks/topology/:id | トポロジーソース Webhook（:id = トポロジーソース id）— ソースを再同期（例: NetBox） |
| POST | /api/webhooks/grafana/:id | Grafana アラート Webhook（:id = データソース id） |
| GET | /api/webhooks/health | Webhook ヘルスチェック |
その他
| メソッド | エンドポイント | 説明 |
|---|---|---|
| GET | /api/health | ヘルスチェック（認証不要） |
| GET | /api/auth/status | 認証状態の確認 |
| POST | /api/auth/setup | 初期パスワード設定 |
| POST | /api/auth/logout | ログアウト |
WebSocket
ws://<host>/ws に接続してリアルタイムメトリクスをストリーミングします。
クライアントメッセージ
// トポロジー更新を購読
{ "type": "subscribe", "topology": "<topology-id>" }
// 特定のノード/リンクをフィルタ
{ "type": "filter", "nodes": ["router1"], "links": ["link-0"] }サーバーメッセージ
{
"type": "metrics",
"data": {
"nodes": {
"router1": { "status": "up" }
},
"links": {
"link-0": {
"status": "up",
"utilization": { "in": 45.2, "out": 12.8 }
}
},
"timestamp": 1705849200000
}
}