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:
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 | An HTTP date, or @-prefixed timestamp, at which the resource became deprecated. It still works. |
Sunset | RFC 8594 | 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 | Points at the replacement endpoint. |
A deprecated-but-live endpoint answers like this:
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"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
| 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, 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.
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, 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.