> ## Documentation index
> Fetch the complete documentation index at: https://contextrepo.com/docs/llms.txt
> Use it to find every page before exploring further.

# Versioning & 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 `Deprecation` HTTP header and a `Sunset` HTTP header naming the retirement date (per [RFC 8594](https://datatracker.ietf.org/doc/html/rfc8594) and [RFC 9745](https://datatracker.ietf.org/doc/html/rfc9745)).
- **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 title="Example response from a deprecated major (illustrative — no version is deprecated today)"
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](https://contextrepo.com/docs/api) and announced on the [changelog](https://contextrepo.com/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 `Deprecation` or `Sunset` headers are emitted today.

## Detecting the Version

Detect the version client-side by inspecting the URL path or the `servers` block in [`/openapi.json`](https://contextrepo.com/openapi.json). Every operation path in the spec carries the `/v1/` prefix.

## What's Next

- [API Reference](https://contextrepo.com/docs/api): Base URL, response envelope, error format, CORS policy, and rate limits.
- [Endpoints](https://contextrepo.com/docs/api/endpoints): Full reference for every REST endpoint with examples.