API ガイド

Yagra が行うことはすべて、1 つの REST API を通じて駆動されます。このページでは、その認証方法とすべてのエンドポイントが従う規約を扱います。エンドポイントごとの詳細は生成された API リファレンスにあり、AI アシスタント向けには専用の入口 — MCP サーバー — が用意されています。

ノースバウンド API

API はコアが API ポート（同梱の compose ファイルでは 8080）で提供し、すべてのパスが /api/v1 プレフィックスの下にあります — およそ 206 エンドポイント、加えてバージョンの付かない 2 つのヘルスプローブ GET /healthz（死活）と GET /readyz（レディネス。高可用性ペアではリーダーだけが 200 を返すため、ロードバランサはこれを使ってルーティングできます）です。

WebUI が行うことはすべて、この同じ API を通ります。 プライベートな裏口はありません。インベントリ画面もダッシュボードもアラート操作も設定ページも、すべては /api/v1 呼び出しの列なので、ブラウザで見えること・できることはすべて自動化できます。プログラムからどうやるか迷ったら、ブラウザのネットワークタブを開いた状態で WebUI で一度やってみれば、正確なリクエストがわかります。

認証

この API を認証する認証情報は 2 種類あり、どちらも Authorization: Bearer <token> で送ります。

セッショントークン — ユーザー名とパスワードと交換する短命のトークン。WebUI が使うもの。
API トークン（yat_…、設定 ▸ API トークンで発行）— 無人クライアント向けの長寿命のトークン。スクリプト・CI ジョブ・連携にはこちらを使ってください。

セッショントークン

POST /api/v1/auth/login で、ユーザー名とパスワードを Bearer のセッショントークンと交換します。

curl -s http://<yagra-host>:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'

{ "token": "<session-token>", "role": "admin" }

以後のリクエストにはこのトークンを付けます。

curl -s http://<yagra-host>:8080/api/v1/nodes \
  -H "Authorization: Bearer <session-token>"

レスポンスにはアカウントのロールも含まれるため、クライアントは自分に何が許可されるかを最初から把握できます。ログインはアカウント単位でも全体でもレート制限されており — 試行が多すぎると Retry-After ヘッダー付きの 429 を返します — POST /api/v1/auth/logout がトークンを失効させます。

API トークン

無人の用途では、ログインをスクリプト化するのではなく API トークンを発行してください。管理者が 設定 ▸ API トークンで作成し、生の値は一度だけ表示されます。送り方はセッショントークンとまったく同じです。

curl -s http://<yagra-host>:8080/api/v1/nodes \
  -H "Authorization: Bearer yat_…"

発行する前に知っておくべきことが 4 つあります。

使える入口が決まっています。 rest を付けて作成したトークンだけが、この REST API に届きます。この項目が存在する前に作られたトークンは mcp のみを持ち、ここでは 401 を返します。アップグレードによって既存の認証情報の権限が広がることはありません。
アカウントとして動作します。 すべてのトークンには所有者がいます。実効ロールはトークンのロールと所有者の現在のロールの低い方なので、アカウントを降格すれば直ちにトークンも狭まり、無効化・削除すれば失効します。所有者にはサービスアカウントを推奨します（ユーザーと SSO を参照）。連携が、設定した担当者に依存しなくなります。
ユーザー管理はできません。 POST /api/v1/users、API トークン自体のエンドポイント、その他ユーザー管理権限で守られたものは、ロールによらずトークンに 403 token_not_permitted を返します。自身の後継を発行できる認証情報は、元の失効を生き延びてしまうからです。
対話的な識別子を持ちません。 「サインイン中のアカウント」を意味するエンドポイント（GET /api/v1/auth/me、個人ダッシュボード）は 403 session_required を返します。

作成時に有効期限（expires_at）を任意で指定でき、省略すれば無期限のままです。同じ画面からいつでも失効させられ、失効は直ちに反映されます。

いくつかのエンドポイントは意図的に認証不要です。クライアントがログインする前にそれらを必要とするためで、いずれもインベントリ・設定・状態を明かしません。

エンドポイント	返すもの
`GET /api/v1/version`	動作中のコアのバージョン
`GET /api/v1/config`	クライアントのブートストラップフラグ（認証・SSO・AI 分析が利用可能かどうか） — シークレットは含みません
`GET /api/v1/openapi.json`	生成された OpenAPI ドキュメント（後述）
`GET /healthz`、`GET /readyz`	死活とレディネスのプローブ

デプロイを公開ダッシュボードのオプション付きで動かしている場合、読み取りエンドポイントはトークンなしで開放されます。書き込みは引き続き認証が必要です。

規約

API 全体が 1 つのルールに従うため、あるエンドポイントで学んだことは残りにもそのまま通用します。

すべて JSON。 リクエストボディもレスポンスも JSON です。ボディを送るときは Content-Type: application/json を設定してください。
作成は 201 を返し、新しいリソースの id を含みます: {"id": "<uuid>"}。
削除は 204 No Content を返します — ボディはなく、安全な範囲で削除は冪等です。
エラーは型付きです。 どの失敗も同じエンベロープで表現されます。
```
{ "error": { "code": "invalid_filter", "message": "…" } }
```
code は安定していて機械可読です — メッセージではなくこちらで分岐してください。message はオペレーターに見せて安全な文章で、内部のエラーテキストを含むことはありません。ステータスコードは通常の意味に従います: 400 は不正な入力、401 は未認証、403 は認証済みだが権限なし、 404 は該当リソースなし、409 は競合、429 はスロットリング（Retry-After ヘッダー付き）、 502 は上流のストアまたはプロバイダの失敗（Yagra 自身の障害である 500 とは区別されます）、 503 はこのデプロイで設定されていない任意サブシステムです。
可用性より先に認証が確認されます。 サブシステムが未設定のエンドポイントが 503 を返すのは、すでに認証・認可を通った呼び出しに対してだけです。未認証のリクエストは常に 401 になります。これは意図的な設計で、認証情報を持たない相手に「どのサブシステムを動かしているか」を開示しないためです。（v0.1.19 より前は、ほとんどのエンドポイントで順序が逆でした。）
大きな一覧はエンベロープに包まれ、上限が付きます。 無制限に伸びうる一覧は素の配列ではなく {"items": [...], "total": <n>, "truncated": <bool>} を返します — たとえば GET /api/v1/thresholds は 1 リクエストあたり最大 500 件のルールを返し、total にはフィルタ前の件数が入ります。?limit= パラメータは上限を狭められますが、広げることはできません。
タイムスタンプは RFC 3339 の文字列（2026-08-01T09:30:00Z）で、レスポンスでも、時刻を取るクエリパラメータでも同じです。

ロールと権限

すべてのリクエストは、トークンが持つロールによってエンドポイントごとに認可されます。

Viewer（閲覧者） — 読み取り専用: インベントリ、メトリクス、アラート、イベント、フロー。
Operator（オペレーター） — Viewer に加えてインシデント対応: アラートの確認（ACK）とミュート、メンテナンスウィンドウの開始と終了、トラブルシュート分析と AI 根本原因説明の実行。
Admin（管理者） — 完全な制御: ノード、プロファイル、しきい値、認証情報、ユーザー、監査ログ。

有効なトークンを持ちながらロールが足りないリクエストには 403 を返します — 未認証のリクエストが受け取る 401 と区別できます。状態を変更するリクエストは自動的に監査ログに記録されます。シングルサインオンを含むロールと権限のモデル全体はユーザーと SSO で説明しています。

OpenAPI ドキュメント

API は自身の契約を GET /api/v1/openapi.json で公開します — すべてのパス、クエリパラメータ、リクエストボディ、レスポンスの形、エラーコードを網羅した OpenAPI 3.1 ドキュメントです。これは ハンドラそのものから生成されるため、サーバーが実際に行うことを記述しており、コードから乖離しえません。WebUI 自身の型と API クライアントも、この同じドキュメントから生成されています。インベントリ・設定・状態を含まないため、認証なしで提供され、どのデプロイでも同一です。

任意の OpenAPI クライアントジェネレータをこれに向ければ、お好みの言語の型付きクライアントが得られます。

curl -s http://<yagra-host>:8080/api/v1/openapi.json -o yagra-openapi.json

同じドキュメントはこのサイトの /openapi.json でも提供しているので、動作中のデプロイがなくてもクライアントを生成できます。

リファレンスを見る

エンドポイントごとのリファレンス — すべてのルートについて、パラメータ、ボディ、レスポンスをドメイン別にまとめたもの — は、その同じドキュメントから生成され、サイドバーでこのページのすぐ下、 /ja/docs/api/reference/ にあります。生成物であるため、それが記述するリリースと常に歩調が合っています。

互換性と変更

API クライアントが気づきうる挙動の変更 — レスポンスの形、ステータスコード、既定値、クエリパラメータの意味、削除されたエンドポイント — は必ずリリースノートに記載され、それぞれが出荷されたバージョンの下に並びます。最近の例としては、素の配列だったレスポンスにエンベロープと上限が付いたこと、削除と作成のエンドポイントが 204／201 に揃ったこと、誰も呼んでいなかったエンドポイントがまるごと削除されたこと、そして一覧のフィールドが非推奨を挟まずより正確なものへ置き換わったこと（v0.2.1 で nodes.source が nodes.kind になり、2 値だった旧フィールドは同じリリースで削除されました）などがあります。自動化がつながっているデプロイをアップグレードする前に、またぐバージョンのノートに目を通してください。その入手先は変更履歴にあります。新しいデプロイの /api/v1/openapi.json からクライアントを再生成すれば、形の変更は機械的に取り込めます。

MCP のツール群

AI アシスタント向けには、専用に作られたもう 1 つの入口があります。/mcp で提供されるオプトインの MCP サーバーで、監視状態をツールとして公開し — 大半は読み取り専用のクエリで、加えて監査される少数の操作 — Claude Code や Claude Desktop のようなクライアントが「落ちているノードは？」に直接答えられるようになります。認証は同じ yat_… の API トークンで、トークンは REST と MCP の両方を使えることも、片方だけに限ることもできます。アシスタント用の認証情報を mcp だけに留められること — それが、この項目が存在する理由です。専用のページもあります: MCP サーバー。