Versions

Five things carry a version, on purpose independently: bumping one does not imply the others changed. This page says where to read each and what a change means for you.

The axes

Axis	Where you read it	Scheme	Changes when
Platform build	version in GET /healthz and /api/status.json	SemVer, derived from the release history	Any module ships — most builds do not touch what an agent can do
Agent capability version	x-capability-version header on every API response · serverInfo.version on MCP connect · capability_version in start_here	Date-anchored, monotonic (2026-09-03.1) — a plain string compare works	The agent-facing read surface changes: new/changed tools, fields, semantics. Every bump has an entry in the capability changelog
API contract	info.version in openapi.json (frozen with this portal build)	SemVer	Paths, schemas or declared responses change
Portal build	versions.json (version, builtAt) · manifest.json (route → content hash) · the badge under every page title	SemVer	The documentation is republished
Pipeline versions	The pipeline catalog	Per pipeline, immutable directories	A pipeline is carved — see Version lifecycle

Detecting change

• Agents: cache capability_version; on every reconnect pass it to start_here as last_seen_version — changed: true plus whats_new is your diff. Between connects, the x-capability-version header on any response tells you the same without a call.
• Docs consumers: compare the stored manifest.json against the current one and re-read only the routes whose hash moved; .md twins carry an ETag.
• Everyone: changelog.json (JSON Feed 1.1) is the machine twin of the release notes — subscribe to it.

Compatibility rules

1. Additive is silent. New endpoints, new tools and new optional fields appear without a contract major bump; ignore fields you do not know.
2. Renames and removals are announced first. They enter the capability changelog under deprecated with the replacement, live side by side for at least one capability version, then move to removed in the release notes.
3. Breaking contract changes bump the contract’s major and the capability version on the same day; the frozen openapi.json of the previous portal build stays available in the release history.
4. Pipeline versions never mutate. A change is a new version directory; the catalog pin decides which one production runs.