Versioning & Deprecation Policy
How the Xantly API is versioned, what counts as a breaking change, and how a deprecation is signalled: Deprecation and Sunset response headers, the OpenAPI deprecated flag, and the minimum notice period before removal.
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. |
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/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, 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.
Checking your integration
To see whether anything you call is deprecated, read the headers off a normal response:
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.