{"name":"Ratatosk agent API","version":"v1","description":"Release intelligence for the CNCF/cloud-native ecosystem: typed changes extracted from release notes, normalized per matter. Every change carries three axes — family (security|breaking|deprecated: what kind of thing it is), bucket (action|check|plan: how to act on it now), and applies_if (a boolean expression you can evaluate against your own setup, rather than prose to read). Declarative and language-neutral; match subjects[].name against your manifests, and quote is always the untranslated source line.","auth":"none (public read); rate limit 1200 requests/minute per IP","endpoints":[{"path":"/v1/projects","note":"Every tracked project: slug (the canonical id used everywhere else), name, tier (graduated|incubating), category, analyzed_releases, image_aliases where a project runs under a different name in clusters (cilium-envoy is envoy; kube-apiserver is kubernetes) — an image or workload matching an alias belongs to that project at the version its tag says — and cluster_core:true on the infrastructure the cluster itself runs on (control plane, datastore, DNS, runtime, CNI/dataplane): every cluster_core project present in a cluster belongs in its stack check. Some cluster_core entries carry a visibility hint — how that component is observed and where it can legitimately be unreadable (etcd may live outside the k8s API; runtimes are read off node status, not pods): an unreadable one is reported as unchecked, never guessed. Small, unpaginated — call once to resolve slugs before check_stack or get_release."},{"method":"GET","path":"/v1/changes","params":{"project":"project slug filter (see /projects)","family":"security|breaking|deprecated — what kind of thing it is (the axis a human subscribes by)","bucket":"action|check|plan|other — how to act NOW. action = applies to everyone, do it. check = only if applies_if matches your setup. plan = announced for later. other = the full record (bot bumps and routine lines)","actionability":"act|plan|note — the stored judgment behind bucket. Omit to exclude note (the full record), which is most rows and mostly dependency bumps","evaluable":"true — only changes whose applies_if can be evaluated by code (clauses present)","since":"cursor: return changes with seq greater than this (seq-ascending = oldest-analyzed first; page through with the returned next_since until it is null — null means caught up; a single page is NOT the newest data)","limit":"page size, default 50, max 200"},"description":"Incremental SYNC feed, ordered by seq ascending (oldest analyzed first) — built for keeping a local copy up to date, not for answering 'what is the latest release of X': use /v1/releases/{project} for that. Two fields are worth knowing: `applies_if` tells you whether a change is yours to act on — when evaluable is true, match its clauses ({kind,name,verb,polarity}) against your own setup instead of parsing the raw sentence. `matter_key` is the identity of the underlying matter across releases: the same security roll-up lands on several branches, and /v1/matters/{key} returns every landing with the advisories each one actually carried.","example":"https://ratatosk.io/v1/changes?family=security&bucket=action&limit=5"},{"method":"GET","path":"/v1/changes/by-entity","params":{"name":"exact identifier to look up (case-insensitive): CVE id, CRD, feature gate, flag, metric, config field, dependency…","kind":"optional: api|crd|feature_gate|flag|metric|config_field|extension|dependency|cve|advisory|subsystem"},"description":"Reverse index: every change touching this identifier.","example":"https://ratatosk.io/v1/changes/by-entity?name=CVE-2026-53329"},{"method":"GET","path":"/v1/matters/{key}","params":{"include":"all — also include the full record (note-level rows). Off by default: those are mostly bot dependency bumps"},"description":"Every release in which one matter appeared, oldest first. Take matter_key verbatim from a change (it is case-sensitive and contains '/' and ':' — url-encode it). Why every occurrence and not just the newest: the same containerd security roll-up landed on five branches carrying 2, 4 and 10 advisories respectively — told only the newest, someone on the 2-advisory branch would assume they were fully covered.","example":"https://ratatosk.io/v1/matters/containerd%2Fadvisory%3Acve-2026-47262"},{"method":"GET","path":"/v1/releases/{project}/{version}","params":{"include":"raw — add the original release note body as raw_notes (capped; raw_notes_truncated=true when cut)."},"description":"One analyzed release: envelope (summary, counts by bucket and family, source) plus all its changes. changes=[] means the release was read and nothing needs you — auditable silence, and notes_total still tells you how many lines were recorded. Omit {version} for the latest analyzed release of the project. {version} is accepted with or without the leading 'v'; a wrong tag 404s with the project's recent tags to retry with.","example":"https://ratatosk.io/v1/releases/envoy/v1.38.3?include=raw"},{"method":"GET","path":"/v1/releases/{project}","params":{"limit":"1-20 — return the newest N analyzed releases as light summaries (counts by bucket and family, highest advisory severity). THE recency path: use this for 'recent releases of X', not the /v1/changes sync feed."},"description":"Newest-first release summaries for one project. Each row carries api_url — fetch it for that release's full changes.","example":"https://ratatosk.io/v1/releases/istio?limit=5"},{"method":"GET","path":"/v1/upgrade/{project}","params":{"from":"required — the version you run today (leading 'v' optional; tag spelling never matters, comparison is numeric)","to":"optional — the version you are upgrading to; omitted = everything up to the latest reviewed release"},"description":"Everything taken on by an upgrade from → to: changes from every release in between, folded per matter_key across release branches (superseded_duplicates counts the folded copies), ordered action → check → plan. Declarative data, not advice — every change carries its source quote and URL; analyses are provided without warranty (see terms). PRIVACY NOTE: the versions sent in from/to reach this server (never written to access logs — the path is normalized to a prefix and query strings are stripped before logging, and IPs are masked). Zero-exposure alternatives: the self-hosted MCP check_stack tool (the comparison runs inside the MCP server process, so versions never leave your infrastructure), or local range-comparison with the version_rank field present on changes and release summaries.","example":"https://ratatosk.io/v1/upgrade/istio?from=1.28.9&to=1.30.3"}],"mcp_server":{"hosted_endpoint":"https://ratatosk.io/mcp","hosted_transport":"streamable-http (stateless)","repository":"https://github.com/garlicKim21/ratatosk-mcp","image":"ghcr.io/garlickim21/ratatosk-mcp","transports":["stdio","streamable-http"],"description":"MCP tools over this API, including check_stack: the version comparison runs inside the MCP server process, so self-hosting it keeps running versions inside your own infrastructure. The hosted endpoint runs that process on the ratatosk server: versions you pass reach it, are processed in memory, and are not written to logs."},"terms":"https://ratatosk.io/terms","docs":"https://ratatosk.io/docs"}