# Versioning & Deprecation Policy

Xantly's API is versioned so you can integrate against it without a change
landing under you unannounced. This page is the contract: how a version is
identified, what counts as a breaking change, and how a removal is signalled
before it happens.

---

## How the API is versioned

The version is the first path segment of every endpoint.

```
https://api.xantly.com/v1/chat/completions
                       ^^
```

`v1` is the current and only version. There is no version header to set, no
date-pinning parameter, and no per-account version. If your base URL ends in
`/v1`, you are pinned.

A new major version is introduced as a new path segment (`/v2`). The two run
side by side; a new version never changes the behaviour of the old one.

---

## What is a breaking change

Breaking changes are shipped only under a new version segment:

- Removing an endpoint, or removing a field from a response
- Renaming a field, or changing its type
- Making a previously optional request field required
- Narrowing an accepted value set, or changing the meaning of a value
- Changing the HTTP status code returned for an existing condition

The following are **not** breaking, and ship into `/v1` continuously:

- Adding a new endpoint
- Adding an optional request field
- Adding a field to a response body or a new response header
- Adding a new value to an open-ended enumeration, such as a new model
  identifier or a new `finish_reason`
- Performance, routing and cost changes that do not alter the response shape

Write clients that ignore unknown response fields and unknown header names.
A client that rejects an unrecognised field will break on a non-breaking
change.

---

## Model availability is not API versioning

The model catalog tracks upstream providers, so models are added and retired
on the providers' schedules, not ours. Model identifiers are data, not API
surface.

`GET /v1/models` is always the authoritative list of what you can call right
now. If you need a model to stay available for a fixed term, that belongs in
an enterprise contract with a pinned allowlist rather than in this policy.

Routing aliases (`xantly/auto`, `xantly/auto-quality`, `xantly/auto-value`,
`xantly/auto-speed`, `xantly/auto-safety`) are API surface and are covered by
this policy. They are the stable way to call the catalog, which is why they
are the recommended default.

---

## How a deprecation is signalled

No `/v1` endpoint is currently deprecated.

When one is, the deprecation is announced in three machine-readable places at
once, so an agent or a client library can detect it without reading this page.

### Response headers

| Header | Meaning |
| --- | --- |
| `Deprecation` | An HTTP-date: when the endpoint became deprecated. Present from the announcement onward. |
| `Sunset` | An HTTP-date: the earliest date the endpoint may stop responding. See [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594). |
| `Link: <...>; rel="deprecation"` | URL of the migration note for this endpoint. |
| `Link: <...>; rel="successor-version"` | URL of the replacement endpoint, when there is a direct one. |

```http
HTTP/1.1 200 OK
Deprecation: Tue, 01 Sep 2026 00:00:00 GMT
Sunset: Sun, 30 Nov 2026 00:00:00 GMT
Link: <https://xantly.com/docs/versioning-and-deprecation>; rel="deprecation"
```

A deprecated endpoint keeps working exactly as before until its `Sunset` date.
The headers are the only change.

### OpenAPI spec

The operation is marked `"deprecated": true` in
[openapi.json](https://xantly.com/openapi.json), with the replacement named in
its description. Generated clients surface this automatically.

### Direct notice

Organizations whose traffic has hit the endpoint in the preceding 30 days are
notified by email to the account owner, and in the dashboard.

---

## Notice periods

| Surface | Minimum notice before removal |
| --- | --- |
| Generally available `/v1` endpoint | 90 days |
| Endpoint documented as beta or preview | 30 days |
| Field within a response body | 90 days, announced in the release notes |
| Security fix that must break behaviour | As long as is safely possible, and never silently |

The clock starts when the `Deprecation` header first appears, not when the
notice email goes out. `Sunset` always reflects the real date.

Terms covering pricing and contractual changes are separate from this policy;
see the [Terms of Service](/terms).

---

## Checking your integration

To see whether anything you call is deprecated, read the headers off a normal
response:

```bash
curl -sI https://api.xantly.com/v1/chat/completions \
  -H "Authorization: Bearer $XANTLY_API_KEY" \
  | grep -iE '^(deprecation|sunset|link):'
```

No output means nothing you called is deprecated.

For agents: the same information is in the OpenAPI spec's `deprecated` flag
per operation, which is the more reliable thing to poll.