Current version
The public catalog lives at /api/v1. Responses include API-Version: 1. The unversioned /api path is human documentation, not a JSON resource. We will not silently change documented JSON fields on v1.
How we version
Breaking changes ship as a new URL prefix (/api/v2) with a new OpenAPI document. Additive fields on existing objects are not breaking. Removing a field, renaming a key, or changing a type is breaking and requires a new major version.
Deprecation signal
When a version or field is deprecated we send Deprecation: true and a Sunset header (HTTP-date) on affected responses, plus a Link relation to /api/versioning. The JSON body may include deprecation.sunset and deprecation.successor. We keep a deprecated major version available for at least 180 days after Sunset is first advertised.
v1 status
v1 is current. No Sunset is advertised. Rate-limit headers (RateLimit, RateLimit-Policy, X-RateLimit-*) are part of the v1 contract and are not a deprecation signal.