API ガイド

Yagra ができることは、すべて 1 つの REST API から動かせます。このページで扱うのは、その認証方法と、すべてのエンドポイントが従う決まりです。

エンドポイントごとの詳細は、生成された API リファレンスにあります。 AI アシスタント向けには、専用の入口として MCP サーバーを用意しています。

ノースバウンド API

API はコアが提供します。ポートは API ポート（同梱の compose ファイルでは 8080）で、すべてのパスは /api/v1 の下にあります。数はおよそ 318 エンドポイントです。正確な数はリファレンスを見てください。OpenAPI ドキュメントから生成しているので、そちらは古くなりません。

これに加えて、バージョンの付かないヘルスプローブが 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 トークンで作ります。生の値が表示されるのは 1 回だけです。送り方は、セッショントークンとまったく同じです。

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

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

使える入口が決まっています。 この REST API に届くのは、rest を付けて作ったトークンだけです。

この項目ができる前に作られたトークンは 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 つの決まりに従います。ですから 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 と、区別できます。

状態を変えるリクエストは、自動的に監査ログに記録されます。例外は PUT /api/v1/preferences です。これはアカウント本人の WebUI の設定を保存するだけです。シングルサインオンを含めた、ロールと権限のモデル全体はユーザーと 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 サーバー。