Versioning & Deprecation Policy

Current contract

The public API is versioned at the path level (/api/v1/..., see API Overview). All routes documented in the Endpoint Catalog are considered stable within the v1 prefix.

Breaking-change policy

A breaking change (removed field, changed response shape, removed endpoint, changed auth requirement) to any documented public route requires:

1. A new version prefix (v2) rather than an in-place breaking change to v1, or
2. If confined to v1 for a genuine security/correctness fix, a minimum notice period published on the API Changelog before the change ships.

Non-breaking additions (new optional fields, new endpoints) ship without a version bump or advance notice, consistent with standard REST practice.

Scope

This policy currently covers the anonymous public route surface only (see Endpoint Catalog for why the full internal surface is not published). A dedicated versioning contract for institutional/enterprise API access does not exist yet -- there is no formal enterprise API tier today. This page is the starting contract that a future institutional-integration agreement would extend, not a currently-sold SLA.

Why this matters for integration partners

Anyone building against the public API (status widgets, release-feed consumers, the desktop auto-updater itself) needs to know a route won't silently change shape. This policy is the same contract the platform's own clients (web, desktop, mobile, admin) implicitly rely on -- documenting it publicly makes it enforceable rather than assumed.