# Versioning and Deprecation
> How IXO APIs are versioned, how a breaking change is announced, and the headers that tell a client an endpoint is going away.
An agent should be able to tell, from the response alone, whether the endpoint it just called still has a future. This page is the contract for that: how versions are named, how long a version lives, and which headers signal a retirement in progress.
## How versions are expressed
Every IXO HTTP API carries its major version in the URL path, so a version is visible in a log line, a bookmark or a cached request without inspecting headers:
```
https://dev.api.emerging.eco/emerging-platform/v1/...
```
A client is pinned by the URL it calls. There is no header-based negotiation and no implicit "latest" alias — `v1` keeps answering `v1` semantics for as long as `v1` is published.
## What counts as breaking
A new major version (`/v2`) is issued only for changes a correct client could not absorb:
| Change | Breaking |
| --- | --- |
| Removing an endpoint, field or enum value | Yes |
| Renaming a field, or changing its type | Yes |
| Making an optional request parameter required | Yes |
| Tightening validation so previously accepted input fails | Yes |
| Adding a new endpoint | No |
| Adding an optional request parameter | No |
| Adding a field to a response body | No |
| Adding a new enum value to a response field | No |
Clients must therefore tolerate unknown response fields and unknown enum values rather than failing closed on them. That single rule is what keeps additive changes non-breaking.
## Deprecation signals
When an endpoint or a version is scheduled for retirement, its responses carry standard headers *before* anything stops working:
| Header | Standard | Meaning |
| --- | --- | --- |
| `Deprecation` | [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html) | An HTTP date, or `@`-prefixed timestamp, at which the resource became deprecated. It still works. |
| `Sunset` | [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html) | An HTTP date after which the resource may stop responding. |
| `Link` with `rel="deprecation"` | RFC 9745 | Points at the notice explaining the change and the migration. |
| `Link` with `rel="successor-version"` | [RFC 5829](https://www.rfc-editor.org/rfc/rfc5829.html) | Points at the replacement endpoint. |
A deprecated-but-live endpoint answers like this:
```http
HTTP/1.1 200 OK
Deprecation: @1780272000
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: ; rel="deprecation"; type="text/html"
Link: ; rel="successor-version"
```
`Deprecation` and `Sunset` are advisory: the endpoint keeps serving normal responses until the sunset date passes. Treat their appearance as a scheduling problem, not an incident.
## Timeline
- **Announcement** — a deprecation is published here and in the release notes on the day the `Deprecation` header first appears.
- **Minimum notice** — at least **180 days** between the `Deprecation` header appearing and the `Sunset` date, for any generally available endpoint.
- **After sunset** — the endpoint answers `410 Gone` with the standard [error envelope](/api-reference/errors), naming its successor in the `hint` field. It is not silently removed, and its path is never reused for different semantics.
Endpoints on a development server — including the `dev.api.emerging.eco` host in the current [OpenAPI description](https://docs.ixo.world/openapi.json) — are pre-release and may change without that notice period. Check the `servers` block before depending on a timeline.
## What a client should do
Log or alert on any response carrying `Deprecation` or `Sunset`. Both are plain HTTP dates, so a check costs one header lookup and turns a future outage into a scheduled task.
Call `/v1/...` rather than constructing a "latest" URL. A pinned client keeps working through the entire deprecation window instead of moving under you.
Unknown response fields and unknown enum values are additive changes, not errors. A client that rejects them turns every non-breaking release into a breaking one.
## Docs endpoints on this site
The machine-readable surfaces published by `docs.ixo.world` itself — the [MCP server](/mcp/model-context-protocol), `llms.txt`, the Markdown mirrors and the OpenAPI document — follow the same rules. The MCP server reports its protocol version in the `initialize` result and in the `Mcp-Protocol-Version` response header; breaking tool changes ship as a new tool name rather than a changed schema on the existing one.