# Versioning and deprecation

> How IXO HTTP APIs name versions, what counts as a breaking change, the headers that announce a retirement, and the notice a client gets before it.

This page is the contract for how IXO HTTP APIs change over time: how versions are named, what
counts as a breaking change, how long a version lives, and which headers signal that an endpoint is
being retired.

Read it when you build a client that has to keep working across releases. After reading it, your
client can tell from a response alone whether the endpoint it called still has a future.

## 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:

```text
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: <https://docs.ixo.world/api-reference/versioning>; rel="deprecation"; type="text/html"
Link: <https://dev.api.emerging.eco/emerging-platform/v2/household-stats>; rel="successor-version"
```

<Note>
  `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.
</Note>

## Timeline

| Stage | Rule |
| --- | --- |
| 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 are pre-release and may change without that notice period. This
includes the `dev.api.emerging.eco` host in the [OpenAPI description](https://docs.ixo.world/openapi.json).
Check the `servers` block before depending on a timeline.

## What a client should do

| Practice | What to do |
| --- | --- |
| Read the headers on every response | 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. |
| Pin the major version explicitly | Call `/v1/...` rather than constructing a "latest" URL. A pinned client keeps working through the entire deprecation window instead of moving under you. |
| Ignore what you do not recognise | 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 files and services published by `docs.ixo.world` itself follow the same rules:
the [MCP server](/mcp/model-context-protocol), `llms.txt`, the Markdown mirrors and the OpenAPI
document. 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.

## Related

<CardGroup cols={2}>
  <Card title="Errors" icon="triangle-exclamation" href="/https/docs.ixo.world/api-reference/errors">
    The error envelope a retired endpoint returns with its 410.
  </Card>
  <Card title="Networks and endpoints" icon="server" href="/https/docs.ixo.world/reference/networks-and-endpoints">
    The hosts and chain ids for each IXO network.
  </Card>
</CardGroup>
