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 | 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
- Announcement — a deprecation is published here and in the release notes on the day the
Deprecationheader first appears. - Minimum notice — at least 180 days between the
Deprecationheader appearing and theSunsetdate, for any generally available endpoint. - After sunset — the endpoint answers
410 Gonewith the standard error envelope, naming its successor in thehintfield. 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 — are pre-release and may change without that notice period. Check the servers block before depending on a timeline.
What a client should 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 surfaces published by docs.ixo.world itself — the MCP server, 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.