REST API リファレンス
manager は /api をルートとする単一の REST API を公開します。web/ の SPA がこれを呼び、任意の HTTP クライアントから直接呼ぶこともできます。GraphQL も、アプリケーショントラフィック用の gRPC もありません（gRPC は manager 内部の geminio トンネル用のみ）。
このページは手書き swagger 仕様ではなくルートカタログです。真実の出所：cmd/ongrid/main.go（chi.Router のマウント）と internal/manager/server/*/http.go（BC ごとハンドラー）。正確なリクエスト / レスポンス構造体フィールドはハンドラーをクリックスルーしてください。
規約
- ベースパス：すべてのルートは
/apiプレフィックス。なのでGET /v1/edgesはhttps://<manager>/api/v1/edgesで到達。 - バージョニング：すべてのルートは
/v1/下。/v2/は無し。後方非互換変更はフィーチャーフラグまたは新ルートで出荷。 - 認証：
Authorization: Bearer ...の bearer JWT。公開ルート（ログイン、リフレッシュ、登録、IM webhook、Prometheus の auth_request プローブ）はミドルウェアをスキップ。下の「公開」表にリスト。 - ロール：
admin、user、viewer。書き込みルートはadmin（またはedge:* / writeのような関連 casbin アクション）が必要。読み取りルートは任意の認証済みロールを受け入れる。viewerはチャットできますが、エージェントの toolbag はClassSafeにフィルタされます。ADR-022 三ロール RBAC 参照。 - エラー：JSON
{"error":"code","message":"human text"}。コードは安定 enum（not_found、invalid_argument、unauthorized、forbidden、conflict）。 - コンテンツタイプ：明示的に注記しない限りすべてのリクエストとレスポンスは
application/json（ストリームチャットは SSE、log/trace 取り込みは OTLP-protobuf または Loki-JSON）。
公開ルート（認証なし）
| メソッド | パス | 目的 |
|---|---|---|
| GET | /healthz | liveness プローブ |
| GET | /readyz | readiness プローブ |
| GET | /internal/auth/dataplane-verify | log/trace 取り込み用 nginx auth_request プローブ |
| POST | /api/v1/auth/login | email+password を JWT に交換 |
| POST | /api/v1/auth/refresh | リフレッシュトークンを新しいアクセストークンに交換 |
| POST | /api/v1/auth/register | セルフ登録（設定でゲート） |
| GET | /api/v1/prometheus/auth | Grafana 埋め込み用 nginx auth_request プローブ |
| POST | /api/v1/im/feishu/events | インバウンド Feishu/Lark コールバック。webhook 署名が認証 |
認証済みルート
iam（users、orgs、sessions）
| メソッド | パス | ロール | ソース |
|---|---|---|---|
| GET | /v1/version | any | cmd/ongrid/main.go（インライン） |
| GET | /v1/me | any | internal/iam/server/http.go |
| GET | /v1/self | any | internal/iam/server/http.go |
| GET | /v1/users | any | ユーザーリスト |
| POST | /v1/users | admin | ユーザー作成 |
| PATCH | /v1/users/{id} | admin | ユーザー更新（name、email） |
| PATCH | /v1/users/{id}/password | self または admin | パスワードローテ |
| PATCH | /v1/users/{id}/role | admin | ロール変更（admin/user/viewer） |
| DELETE | /v1/users/{id} | admin | ユーザー削除 |
| GET | /v1/orgs | any | 組織リスト |
| POST | /v1/orgs | admin | 組織作成 |
| PATCH | /v1/orgs/{id} | admin | 組織更新 |
| DELETE | /v1/orgs/{id} | admin | 組織削除 |
| GET | /v1/orgs/{id}/members | any | メンバーリスト |
| POST | /v1/orgs/{id}/members | admin | メンバー追加 |
| PATCH | /v1/orgs/{id}/members/{user_id} | admin | メンバーロール変更 |
| DELETE | /v1/orgs/{id}/members/{user_id} | admin | メンバー削除 |
edge（トンネル接続エージェント）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| POST | /v1/edges | edge:* | edge 作成、access+secret キー発行 |
| GET | /v1/edges | any | edge リスト |
| GET | /v1/edges/{id} | any | edge 詳細取得 |
| DELETE | /v1/edges/{id} | edge:* | edge 削除 |
| POST | /v1/edges/{id}/rotate-secret | edge:* | secret キーローテ |
| POST | /v1/edges/{id}/upgrade | edge:* | 明示 URL+sha256 でリモートエージェントアップグレードをトリガー |
| POST | /v1/edges/{id}/upgrade-package | edge:* | ワンクリックバンドルアップグレード（ADR-024） |
| GET | /v1/edges/{id}/processes | any | 読み取り専用プロセスリスト（オンデマンド RPC） |
| GET | /v1/edges/{id}/plugins | any | edge の設定済み + ライブプラグインリスト（ヘルス付き） |
| PUT | /v1/edges/{id}/plugins/{name} | edge:plugin | プラグインの有効化/無効化 + チューン |
| GET | /v1/integrations/plugin-counts | any | グローバルプラグイン有効/無効カウント（ホームページタイル用） |
device（ホストエンティティ、トンネル状態と切り離し）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/devices | any | ホストデバイスリスト |
| GET | /v1/devices/{id} | any | デバイス詳細取得 |
| PATCH | /v1/devices/{id} | device:* | 表示名、tags 更新 |
| DELETE | /v1/devices/{id} | device:* | デバイス削除 |
| PATCH | /v1/devices/{id}/roles | device:* | ロール割り当て（db、web、cache...） |
| GET | /v1/devices/{id}/edges | any | このデバイスを現在表す edge |
| GET | /v1/devices/{device_id}/shell | webshell | WebSSH ストリームをオープン（websocket アップグレード） |
topology（型付き CMDB）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/topology/node-types | any | ノードタイプスキーマリスト |
| POST | /v1/topology/node-types | topology:* | ノードタイプ作成 |
| GET | /v1/topology/node-types/{name} | any | 1 ノードタイプ取得 |
| DELETE | /v1/topology/node-types/{name} | topology:* | ノードタイプ削除 |
| GET | /v1/topology/nodes | any | ノードリスト（type、tag でフィルタ） |
| POST | /v1/topology/nodes | topology:* | ノード作成 |
| GET | /v1/topology/nodes/{id} | any | ノード取得 |
| PATCH | /v1/topology/nodes/{id} | topology:* | ノード更新 |
| DELETE | /v1/topology/nodes/{id} | topology:* | ノード削除 |
| GET | /v1/topology/relation-types | any | リレーションタイプスキーマリスト |
| POST | /v1/topology/relation-types | topology:* | リレーションタイプ作成 |
| GET | /v1/topology/relation-types/{name} | any | 1 リレーションタイプ取得 |
| DELETE | /v1/topology/relation-types/{name} | topology:* | リレーションタイプ削除 |
| GET | /v1/topology/relations | any | エッジ（リレーション）リスト |
| POST | /v1/topology/relations | topology:* | リレーション作成 |
| GET | /v1/topology/relations/{id} | any | リレーション取得 |
| PATCH | /v1/topology/relations/{id} | topology:* | リレーション更新 |
| DELETE | /v1/topology/relations/{id} | topology:* | リレーション削除 |
alert（rules、incidents、channels）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/alert-rules | any | ルールリスト |
| POST | /v1/alert-rules | alert:* | ルール作成 |
| GET | /v1/alert-rules/{id} | any | ルール取得 |
| PUT | /v1/alert-rules/{id} | alert:* | ルール置換 |
| DELETE | /v1/alert-rules/{id} | alert:* | ルール削除 |
| POST | /v1/alert-rules/{id}/enabled | alert:* | enabled フラグ反転 |
| POST | /v1/alert-rules/preview | alert:* | 現在のデータに対しルール定義をドライラン |
| GET | /v1/alerts/incidents | any | インシデントリスト（フィルター：status、severity、scope） |
| GET | /v1/alerts/incidents/{id} | any | インシデント取得 |
| GET | /v1/alerts/incidents/{id}/events | any | イベントタイムライン |
| POST | /v1/alerts/incidents/{id}/ack | any | acknowledge |
| POST | /v1/alerts/incidents/{id}/resolve | any | resolved マーク |
| POST | /v1/alerts/incidents/{id}/silence | any | N 時間サイレンス |
| GET | /v1/alerts/incidents/{id}/investigation | any | AI 生成調査レポート取得 |
| POST | /v1/alerts/incidents/{id}/investigation | any | 調査トリガーまたは再実行 |
| GET | /v1/alerts/runtime-info | any | evaluator ペース + 直近サイクル統計 |
| GET | /v1/notification-channels | any | チャネルリスト |
| POST | /v1/notification-channels | channel:* | チャネル作成 |
| GET | /v1/notification-channels/{id} | any | チャネル取得 |
| PUT | /v1/notification-channels/{id} | channel:* | チャネル置換 |
| DELETE | /v1/notification-channels/{id} | channel:* | チャネル削除 |
| POST | /v1/notification-channels/{id}/test | channel:* | 合成通知送信 |
ルールの JSON 形は アラートルールスキーマ を参照。
aiops（chat、agents、models）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/agents | any | エージェントペルソナリスト |
| GET | /v1/agents/{name} | any | ペルソナ詳細取得 |
| DELETE | /v1/agents/{name} | agent:* | 組み込み / ディスクペルソナの削除（稀。通常は custom のみ削除可能） |
| POST | /v1/agents/custom | agent:* | ユーザー定義ペルソナ作成 |
| PATCH | /v1/agents/custom/{name} | agent:* | ユーザーペルソナ更新 |
| DELETE | /v1/agents/custom/{name} | agent:* | ユーザーペルソナ削除 |
| GET | /v1/chat/sessions | any | セッションリスト |
| POST | /v1/chat/sessions | any | セッション作成 |
| PATCH | /v1/chat/sessions/{id} | any | セッションのリネーム / タグ付け |
| DELETE | /v1/chat/sessions/{id} | any | セッション削除 |
| GET | /v1/chat/sessions/{id}/messages | any | メッセージ履歴 |
| POST | /v1/chat/sessions/{id}/messages | any | メッセージ送信（非ストリーミング、最終返信を返す） |
| POST | /v1/chat/sessions/{id}/messages/stream | any | メッセージ送信（トークン + ツール呼び出しイベントの SSE ストリーム） |
| GET | /v1/aiops/models | any | 利用可能なプロバイダー + モデル（設定済み API キーでゲート） |
| POST | /v1/aiops/query-translate | any | LLM 支援の PromQL / LogQL / TraceQL 合成 |
| GET | /v1/aiops/mentions/search | any | @edge、@device、@dashboard メンションのオートコンプリート |
| GET | /v1/usage/today | any | 現在 UTC 日のトークン使用量 |
ペルソナの markdown フロントマター形は エージェントペルソナフォーマット を参照。
knowledge（RAG、vault、repos、uploads）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/knowledge/docs | any | ドキュメントリスト（ツリー） |
| POST | /v1/knowledge/docs | knowledge:* | ドキュメント作成 |
| GET | /v1/knowledge/docs/{id} | any | ドキュメント取得 |
| PATCH | /v1/knowledge/docs/{id} | knowledge:* | ドキュメント本文編集 |
| PATCH | /v1/knowledge/docs/{id}/move | knowledge:* | 別パスに移動 |
| DELETE | /v1/knowledge/docs/{id} | knowledge:* | ドキュメント削除 |
| GET | /v1/knowledge/paths | any | パスノードリスト（ツリー用） |
| GET | /v1/knowledge/repos | any | Git リポリスト |
| POST | /v1/knowledge/repos | knowledge:* | リポ登録 |
| DELETE | /v1/knowledge/repos/{id} | knowledge:* | リポ削除 |
| POST | /v1/knowledge/repos/{id}/sync | knowledge:* | 再同期トリガー |
| POST | /v1/knowledge/upload | knowledge:* | .md / .txt / .pdf / .docx アップロード（docextract でパース） |
| GET | /v1/knowledge/search | any | RAG クエリ（チャンク + スコアを返す） |
| POST | /v1/knowledge/vault/sync | knowledge:* | 組み込み vault を GitHub から再 pull |
| GET | /v1/knowledge/ssh-identities | knowledge:* | Git 認証用 SSH キーリスト |
| POST | /v1/knowledge/ssh-identities | knowledge:* | 既存 SSH キー登録 |
| POST | /v1/knowledge/ssh-identities/generate | knowledge:* | 新規キーペア生成（秘密鍵はサーバーを離れない） |
| PATCH | /v1/knowledge/ssh-identities/{id} | knowledge:* | identity 編集（name、comment） |
| DELETE | /v1/knowledge/ssh-identities/{id} | knowledge:* | identity 削除 |
skill（toolbag 内省）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/skills | any | スキルリスト（manager-scope + edge-scope） |
| GET | /v1/skills/{key} | any | スキル詳細取得（schema、description、scope、class） |
| POST | /v1/skills/{key}/execute | skill:* | 直接スキル実行（テスト / デバッグ） |
ディスク上の skill.json の形は スキルマニフェスト を参照。
logs / traces（読み取り専用プロキシ）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/logs/query_range | any | プロキシ LogQL query_range |
| GET | /v1/logs/labels | any | プロキシ label-names |
| GET | /v1/logs/labels/{name}/values | any | プロキシ label-values |
| GET | /v1/traces/search | any | プロキシ TraceQL /api/search |
| GET | /v1/traces/{trace_id} | any | ID で 1 トレース |
| GET | /v1/traces/tags/{tag}/values | any | プロキシ /api/search/tag/.../values |
monitor（dashboards / panels）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/monitor/panels | any | パネルリスト |
| POST | /v1/monitor/panels | monitor:* | パネル作成 |
| PATCH | /v1/monitor/panels/{id} | monitor:* | パネル編集 |
| DELETE | /v1/monitor/panels/{id} | monitor:* | パネル削除 |
| GET | /v1/observability/dashboards/{uid} | any | レンダー準備済み Grafana ダッシュボード JSON |
metric（edge ごとメトリクススナップショット）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/edges/{id}/metrics | any | 最新のクローズドセットホストメトリクススナップショット |
prometheus（admin）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| POST | /v1/prometheus/launch | admin | 組み込み Prometheus を（再）起動 |
| POST | /v1/prometheus/query_range | any | LLM ツール向け query_range（正規化された行列を返す） |
imbridge（チャット画面 —— Slack / Telegram / Lark / DingTalk / WeCom）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/im/apps | any | 接続された IM アプリのリスト |
| POST | /v1/im/apps | im:* | IM アプリ登録 |
| GET | /v1/im/apps/{id} | any | アプリ取得 |
| PUT | /v1/im/apps/{id} | im:* | アプリ更新 |
| DELETE | /v1/im/apps/{id} | im:* | アプリ削除 |
| POST | /v1/im/apps/{id}/reveal | admin | マスクされた secret を表示 |
marketplace（スキルパック）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/marketplace/registries | any | 設定済みレジストリのリスト |
| GET | /v1/marketplace/installed | any | インストール済みパックのリスト |
| POST | /v1/marketplace/install | marketplace:* | レジストリからパックをインストール |
| DELETE | /v1/marketplace/installed/{pack_id} | marketplace:* | パックアンインストール |
setting（システム設定：integration、デフォルト、secrets）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/system-settings | any | 可視設定リスト |
| PUT | /v1/system-settings/{category}/{key} | admin | 設定 upsert |
| DELETE | /v1/system-settings/{category}/{key} | admin | 設定削除 |
| GET | /v1/system-settings/{category}/{key}/reveal | admin | マスクされた secret を表示 |
integration（接続テスト）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| POST | /v1/integrations/grafana/sync | admin | ダッシュボード + データソース同期 |
| POST | /v1/integrations/grafana/test | admin | Grafana 接続テスト |
| POST | /v1/integrations/llm/invalidate | admin | キャッシュ LLM クライアントを無効化（API キー再読み込み強制） |
| POST | /v1/integrations/loki/test | admin | Loki 接続テスト |
| POST | /v1/integrations/prom/test | admin | Prometheus 接続テスト |
| POST | /v1/integrations/tempo/test | admin | Tempo 接続テスト |
| POST | /v1/integrations/websearch/test | admin | SearXNG / web-search バックエンドテスト |
webshell（トンネル越しの対話的シェル）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/devices/{device_id}/shell | webshell | WebSocket アップグレード SSH ストリームを開く |
| GET | /v1/webshell/sessions | any | アクティブセッションリスト |
| DELETE | /v1/webshell/sessions/{id} | webshell | セッション強制終了 |
audit（admin log）
| メソッド | パス | ロール | 説明 |
|---|---|---|---|
| GET | /v1/admin/audit-logs | admin | テナント全体の監査証跡（HLD-010） |
ページング
リストエンドポイントは opaque カーソルを使用：
text
GET /v1/edges?limit=50&cursor=eyJpZCI6MTAwMH0レスポンスは {"items":[...], "next_cursor":"...", "total":...} を持ちます。next_cursor は最後のページで空。
レート制限
オープンソースビルドにグローバルレート制限はありません。LLM バジェットゲート（ONGRID_LLM_DAILY_TOKEN_LIMIT）がチャットトラフィックを制限します —— それ以外のエンドポイントは manager の前に置いたもの（nginx、自前ゲートウェイ）に依存します。
バージョニング
GET /v1/version は {"manager_version":"vX.Y.Z"} を返します。SPA がこれを読み、エージェントバージョンが manager からドリフトした edge をフラグします。アップグレードツールに使用してください。
関連
- 環境変数 —— API の挙動を制御するもの。
- アラートルールスキーマ ——
/v1/alert-rulesのリクエストボディ。 - スキルマニフェスト ——
/v1/skillsとマーケットプレースインストールのリクエストボディ。 - エージェントペルソナフォーマット ——
/v1/agents/customのリクエストボディ。