REST API

このページでは、change（データを理解する）をプログラムから直接取得できる、読み取り専用の公開 API /v1 の使い方を説明します。

前提条件

必要なのは curl だけです。認証も API キーもサインアップも要りません。
制限: IP あたり毎分 1200 回。超えると 429 が返り、何秒後に再試行すればよいかを Retry-After ヘッダが伝えます。
時刻はすべて UTC、レスポンスは JSON です。
仕様は API 自身が提供します。https://ratatosk.io/v1 を開けばエンドポイント・パラメータ・例が一画面に並びます。

change のかたち

ここで返るのはすべて change です。change 1 件はリリースが行ったこと 1 つで、絞り込みと判断に使える 3 つの軸を伴います。

軸	値	何に答えるか
`family`	`security` `breaking` `deprecated`	どの種類か — 人が購読するときに選ぶ軸
`bucket`	`action` `check` `plan` `other`	いまどう動くか
`applies_if`	真偽式	自分に該当するか

振り分けの基準は bucket です。action はそのバージョンの全インストールに該当します。check は applies_if が自分の構成と一致する場合だけ該当するので、何かを勧める前にその条件を確かめてください。plan は将来に向けた予告、other は全件記録 — bot の依存関係更新や定型行なので既定では除外されます。

bucket はウェブ画面や週次メールと同じ規則でサーバが計算して載せます。だから 3 つの表面が同じ数を答えます。ほかのフィールドから再計算しないでください。

エンドポイント

パス	用途
`GET /v1`	自己記述インデックス — 全エンドポイント・パラメータ・例
`GET /v1/changes`	増分同期フィード。`project` `family` `bucket` `actionability` `evaluable` `since` `limit` で絞り込み。`limit` は 1〜200（既定 50）
`GET /v1/changes/by-entity`	逆引き: 識別子 1 つ（CVE・CRD・フラグなど）に触れたすべての change。パラメータ: `name`（必須）・`kind`
`GET /v1/matters/{key}`	1 つの事案が登場したリリースすべて、古い順。`?include=all` で note 級の記録も
`GET /v1/projects`	追跡中のプロジェクト全一覧。フィールドは下の「プロジェクトメタデータ」参照
`GET /v1/releases/{project}/{version}`	リリース 1 件: エンベロープとその change すべて。`include=raw` で原文（`raw_notes`）を追加、切り詰めた場合は `raw_notes_truncated: true`。原文には出典表示 `raw_notes_notice` が付きます — 原文を再掲するならそのまま残してください
`GET /v1/releases/{project}`	そのプロジェクトの最新の分析済みリリース（バージョン省略）
`GET /v1/releases/{project}?limit=N`	最新 N 件のリリース要約 — 新しい順の取得経路（1〜20、範囲外は黙って丸められます）
`GET /v1/upgrade/{project}?from=&to=`	アップグレードで引き受けるものすべて。リリースブランチをまたいで `matter_key` 単位に畳みます。`to` は `from` より上である必要があります（同じか下なら空区間 → 400）、`to` を省略すると最新まで。バージョンがサーバに送られます — 下の「バージョン情報をどこまで送るか」参照

例

このページのレスポンス例はすべて 2026-08-10 に実際に受け取ったものを短くしたものです（省略箇所は …）。データは増え続けるので、いま実行すると件数や値は異なります。

全員に該当するセキュリティ change:

curl "https://ratatosk.io/v1/changes?family=security&bucket=action&limit=2"

{
  "changes": [
    {
      "change_id": "argo:v3.5.0:c140f331",
      "matter_key": "argo/dependency/formidable#value_changed",
      "project": "argo",
      "version": "v3.5.0",
      "version_rank": [3, 5, 0],
      "family": "security",
      "actionability": "act",
      "bucket": "action",
      "kind": "value_changed",
      "applies_if": { "evaluable": false, "mode": "universal", "clauses": [], "raw": null },
      "advisories": [],
      "subjects": [ { "kind": "dependency", "name": "formidable", … } ],
      "quote": "chore(deps): update dependency formidable to v2.1.3 [security]",
      "source_url": "https://github.com/argoproj/argo-cd/releases/tag/v3.5.0",
      "seq": 1415
    },
    … もう 1 件 …
  ],
  "next_since": 1421
}

特定の CVE を扱った change を探す — 1 回の呼び出しで全プロジェクトを横断します:

curl "https://ratatosk.io/v1/changes/by-entity?name=CVE-2026-41178"

{
  "changes": [
    {
      "change_id": "buildpacks:v0.40.9:83576398",
      "matter_key": "buildpacks/advisory:cve-2026-41178",
      "project": "buildpacks",
      "version": "v0.40.9",
      "family": "security",
      "bucket": "action",
      "advisories": [
        { "id": "CVE-2026-41178", "severity": "medium" },
        { "id": "GO-2026-5158", "severity": "medium" }
      ],
      "subjects": [
        { "kind": "dependency", "name": "go.opentelemetry.io/otel", … },
        { "kind": "cve", "name": "cve-2026-41178", "name_full": "CVE-2026-41178", … }
      ],
      …
    }
  ]
}

名前が曖昧なときは kind で絞ります。値と意味はデータを理解するにあります:

curl "https://ratatosk.io/v1/changes/by-entity?name=challenges.acme.cert-manager.io&kind=crd"

最新リリースの要約 — バージョンごとに層別・種類別の件数が付きます:

curl "https://ratatosk.io/v1/releases/istio?limit=3"

{
  "project": "istio",
  "count": 3,
  "releases": [
    {
      "version": "1.29.6",
      "version_rank": [1, 29, 6],
      "released_at": "2026-07-16T16:51:06.000Z",
      "reviewed_at": "2026-08-09T04:33:14.694Z",
      "changes_total": 0,
      "by_bucket": {},
      "by_family": {},
      "max_severity": null,
      "notes_total": 5,
      "api_url": "https://ratatosk.io/v1/releases/istio/1.29.6"
    },
    … もう 2 件 …
  ]
}

changes_total: 0 なのに notes_total: 5 — これは監査可能な沈黙です。リリースは読まれ、5 行が記録され、そのどれもあなたの対応を要さない、という意味です。欠落ではなく答えです。

アップグレードで引き受けるものすべて:

curl "https://ratatosk.io/v1/upgrade/istio?from=1.27.0&to=1.27.7"

{
  "project": "istio",
  "from": "1.27.0",
  "to": "1.27.7",
  "releases_covered": ["1.27.6", "1.27.7"],
  "changes_total_before_dedupe": 5,
  "changes": [
    {
      "change_id": "istio:1.27.7:8a66e585",
      "matter_key": "istio/advisory:cve-2025-61732",
      "family": "security",
      "bucket": "action",
      "kind": "defect_corrected",
      "advisories": [ { "id": "CVE-2025-61732", "severity": "high" } ],
      "quote": "- CVE-2025-61732 (CVSS score 8.6, High): A discrepancy between how Go and C/C++ …",
      …
    },
    … action → check → plan の順にさらに …
  ],
  "privacy": "The versions sent in from/to reach this server (they are not written to access logs — …",
  …
}

1 つの事案をリリースをまたいで追う

matter_key は根にある事案の同一性で、リリースやブランチをまたいでも変わりません。 /v1/matters/{key} は最新の 1 件ではなく、登場したすべてのリリースを古い順に返します:

curl "https://ratatosk.io/v1/matters/containerd%2Fadvisory%3Acve-2026-47262"

キーは change からそのままコピーして URL エンコードしてください — 大文字小文字を区別し、/ と : を含みます。

なぜ全件なのか: 同じ containerd のセキュリティロールアップが 5 つのブランチに、それぞれアドバイザリ 2 件・4 件・10 件を伴って着地しました。最新の 1 件だけを見せると、2 件のブランチを使っている人は自分が全部カバーされたと思ってしまいます。

その change が自分に該当するかを判断する

applies_if は文章ではなく真偽式です:

"applies_if": {
  "evaluable": true,
  "mode": "any_of",
  "clauses": [
    { "kind": "api", "name": "ScheduleJobAlpha1", "verb": "uses", "polarity": "present" }
  ],
  "raw": null
}

evaluable が true なら、文章を解釈する代わりに節（clause）を自分のマニフェストと突き合わせれば済みます。mode は all_of・any_of・universal（全員該当）で、各節が探すべき対象を指します。evaluable が false の場合は raw に元の文が入ります — 持っていない構造を作り出す代わりに、無いと明示します。

機械的に判定できるものだけを見るには ?evaluable=true で絞ってください。

深刻度の判断

深刻度は change ではなく引用されたアドバイザリに付きます。advisories の各項目は、分析時点で固まった値ではなく、公式の出典から読み直した現在の値を持ちます。リリース要約はその最大値を max_severity として出します。

advisories: [] は「評価なし」ではなく、リリースノートがアドバイザリ ID を挙げなかったという意味です。

増分取得

/v1/changes は seq の昇順 — 分析が古いものからです。したがって最初のページは最新データではありません。レスポンスの next_since を次のリクエストの since に渡すと、新しく増えた分だけを受け取れます:

# 1 回目: 最初から
curl "https://ratatosk.io/v1/changes?limit=100"
# → { "changes": [ ... ], "next_since": 295 }

# 2 回目: 受け取った next_since を since に
curl "https://ratatosk.io/v1/changes?limit=100&since=295"
# → { "changes": [ ... ], "next_since": 398 }

next_since はそのページ最後の change の seq です — 件数でもオフセットでもありません。シーケンス番号は連続しないので、自分で計算せず受け取った値をそのまま返してください。next_since が null で返れば、取るものがもう無い＝ローカルの写しが最新という意味です。since=null は送らないでください — 400 になります。

bucket=other の行は要求しない限り除外されます。記録の大半を占め、多くは依存関係の更新です。

このカーソルはローカルの写しを保つためのものです。「X の最新リリース」を知りたいときは /v1/releases/{project} を使ってください。

プロジェクトメタデータ

GET /v1/projects の各項目には slug・name・tier・category・ analyzed_releases（分析済みリリース数）のほか、次のフィールドがあります:

image_aliases: そのプロジェクトが別のイメージ名で動いている場合の、その名前の一覧。稼働中のイメージ名からスラッグを逆引きするためのものです。
cluster_core: true: クラスタ基盤コンポーネント（コントロールプレーン・データストア・DNS・ランタイム・CNI/データプレーン）であることを示す印。自分のスタックに登録していなくても点検する価値があります。
visibility: 一部の項目にだけ付く観測ヒント。そのコンポーネントが通常の問い合わせでは見えないことがあると伝えます — たとえば etcd は Kubernetes API の外で動いていることがあります。

レスポンスではこう見えます:

{
  "projects": [
    …
    { "slug": "envoy", "name": "Envoy", "tier": "graduated",
      "category": "networking", "analyzed_releases": 22,
      "image_aliases": ["cilium-envoy"], "cluster_core": true },
    …
  ],
  "count": 76
}

バージョン情報をどこまで送るか

「アップグレードすると何を引き受けるのか」に答える道は 1 つではなく、自分の構成がどこまでサーバに届くかが違います。全体の比較は MCP サーバにあり、この API の中では 2 つの選択肢があります。

ローカル区間比較: change を取得して version_rank で自分で比較します。バージョンは自分のマシンから出ません。version_rank は表記に依存しない並び替え用の数値配列で、v0.42.0 は [0, 42, 0] になります。規則はこうです — その順位が現在のバージョンより大きく、目標バージョン以下なら、その change は区間に入ります。
/v1/upgrade: サーバが区間を計算します。from/to のバージョンはサーバに届きますが、処理中にメモリを通るだけでアクセスログには書かれません — クエリはログ前に除去され、パスは接頭辞に正規化され、IP はマスクされます（プライバシーポリシー）。レスポンスの privacy フィールドがこの取り扱いを明示します。

手で確かめるとこうなります:

{ "change_id": "istio:1.27.7:8a66e585", "project": "istio",
  "version": "1.27.7", "version_rank": [1, 27, 7], … }

自分のバージョンが [1, 27, 0]、目標が [1, 27, 7] なら [1, 27, 0] < [1, 27, 7] ≤ [1, 27, 7] — この change は区間内です。

プロジェクトのタグを数値として並べられない場合、version_rank は null です（モノレポのタグ flagd/v0.16.1、チャネルのタグ lts-4081.3.8 など）。推測せず、区間比較から除外します。

その他の機械可読エンドポイント

/md（マークダウンネゴシエーション）: ホーム・/releases・リリース詳細を Accept: text/markdown ヘッダ付きで要求すると、HTML の代わりにマークダウンが返ります。エージェントが解析しやすい形式です。
/.well-known/api-catalog: このサイトが提供する API の機械可読カタログ（RFC 9727）。
/.well-known/mcp/server-card.json: MCP サーバカード — エージェントが MCP サーバを機械的に発見するための標準文書。MCP サーバを参照。

トラブルシューティング

404（バージョンタグ）: プロジェクトによって v 接頭辞が異なります（envoy は v1.39.0、istio は 1.28.9）。/v1/releases/{project}/{version} は両方の表記を受け付けますが、それでもタグが違う場合、404 のレスポンス本文にそのプロジェクトの最近の分析済みタグが含まれます。その中の 1 つをそのまま使ってください。
404（事案キー）: matter_key は / と : を含み、大文字小文字を区別します。 URL エンコードし、change からそのままコピーしてください。
429: 毎分 1200 回の制限を超えました。Retry-After ヘッダの秒数だけ待ってから再試行してください。リクエスト数を減らすには next_since カーソルで増分だけを取得します — 毎回全体を取り直すよりはるかに少なくなります。
知らないプロジェクトスラッグ: まず GET /v1/projects を確認してください。稼働中のイメージ名とスラッグが一致しない場合は、image_aliases からそのイメージ名を探してください。
結果が空でおかしいと感じたら: bucket=other は既定で除外されます。全件記録が必要なら actionability=note または bucket=other を付けてください。

利用条件

分析は AI が生成し、無保証で提供されます。すべての分析は根拠となった出典にリンクします。利用規約をご覧ください。