Context Repo DocsVersioning & Deprecation Policy
How the Context Repo REST API is versioned — additive-only changes within /v1, side-by-side majors, and a six-month deprecation runway signaled with Deprecation and Sunset headers.
The REST surface is versioned with a URL prefix (/v1/). This page is the canonical policy for how versions evolve, how breaking changes ship, and how deprecation is signaled — so agents and integrations can rely on a surface that never changes without warning.
The Contract for a Published Version
- Backwards compatibility within a major version. Inside
/v1/, fields and endpoints are additive only — new optional fields and new endpoints may appear at any time, but existing fields will not be renamed or repurposed, and existing endpoints will not have their semantics changed. - New majors get their own prefix. A future
/v2/will run side-by-side with/v1/rather than replace it. Clients pin to the prefix they were written against. - Deprecation runway. When a future major is introduced, the prior major remains available for at least six months. During the runway, responses from the deprecated major will include a
DeprecationHTTP header and aSunsetHTTP header naming the retirement date (per RFC 8594 and RFC 9745). - Breaking changes are never silent. If a
/v1/endpoint cannot be evolved additively, it ships as a new endpoint at a new path under/v1/or moves to/v2/— the old path keeps its prior contract.
How Deprecation Is Signaled
Once a major version enters its runway, every response from that version will carry both headers alongside a migration pointer:
HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://contextrepo.com/docs/api/versioning>; rel="deprecation"Clients should treat the presence of a Deprecation header as the cue to plan a migration, and the Sunset date as the hard deadline. A migration guide will be published in the docs and announced on the changelog before any runway begins.
Current Status
- The current — and only — major is
v1. - No version is deprecated and no sunset is scheduled, so no
DeprecationorSunsetheaders are emitted today.
Detecting the Version
Detect the version client-side by inspecting the URL path or the servers block in /openapi.json. Every operation path in the spec carries the /v1/ prefix.