> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning.md).

# API Versioning

The Nexus Exchange API is versioned with the OpenAPI specification published at [`nexus-xyz/nexus-exchange-api`](https://github.com/nexus-xyz/nexus-exchange-api). Each SDK release is pinned to a specific spec version, and the API declares a **minimum supported version** that it will accept. This page explains how to send your version, what happens when it falls below the minimum, and how deprecations are signalled.

## Sending your version

Send the spec tag your client was built against in a request header, in addition to (not instead of) your `User-Agent`:

```
X-Nexus-Api-Version: v0.6.2
```

The value is the released spec tag (a leading `v` is optional — `v0.6.2` and `0.6.2` are equivalent). The official SDKs are pinned to a spec version and send this header for you by default; you only need to set it manually if you build your own client.

The header is **optional during the current pre-1.0 grace period** — requests without it are accepted. This will tighten as the API approaches GA; send the header now so your integration is forward-compatible.

## Minimum supported version

To avoid stranding integrations on breaking changes — while not carrying permanent backward-compatibility baggage before there is a large external client base — the API accepts requests only at or above a published minimum version.

**Pre-1.0 support policy.** Until the 1.0 GA release, the minimum supported version may advance aggressively as breaking changes ship. Breaking changes are a minor bump (`0.X.0`); non-breaking changes are a patch bump. The operational practice when the minimum advances is to first move versions below it into a deprecation window (see below) before retiring them, so an active integration gets a signalled window to upgrade. Treat the `Deprecation` / `Sunset` response headers as your authoritative upgrade signal rather than assuming a fixed grace period.

You can always read the current threshold programmatically — see [Discovering the current version](#discovering-the-current-version).

## Below the minimum: `426 Upgrade Required`

A request whose version is below the minimum is rejected with **HTTP 426 Upgrade Required** and a machine-readable JSON body:

```json
{
  "code": "api_version_unsupported",
  "message": "Unsupported or missing API version. Fetch the current OpenAPI spec at spec_url, regenerate your client, and retry with the X-Nexus-Api-Version header.",
  "min_version": "0.6.0",
  "current_version": "0.6.2",
  "spec_url": "https://github.com/nexus-xyz/nexus-exchange-api/releases",
  "docs_url": "https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning"
}
```

The response also carries an `X-Nexus-Api-Min-Version` header with the same floor, for clients that read headers without parsing the body.

**Self-healing for agents.** Because the body carries `spec_url` and both the minimum and current versions, an automated client can recover from version skew on its own: fetch the current spec, regenerate its client, and retry — no human in the loop. A version-skew error is a recoverable condition, not silent breakage.

## Deprecation and sunset

A version that is still accepted but scheduled for retirement is served normally, with standard advisory headers on every response:

* **`Deprecation`** ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) — signals that the version you sent is deprecated.
* **`Sunset`** ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) — the date after which that version will be rejected with `426`.
* **`Link: <…>; rel="deprecation"`** — points to this page.

Treat a `Deprecation` header as a prompt to upgrade before the `Sunset` date. Nothing about the request fails while it is in the deprecation window; only the advisory headers are added.

## Header parsing details

A few specifics worth knowing if you build your own client rather than using an official SDK:

* **Pre-release tags compare by release lineage.** A pre-release such as `0.6.0-rc.1` is treated as `0.6.0` for the minimum check — everything from the first `-` or `+` is stripped. So a pre-release satisfies a floor equal to its release version.
* **An unparseable version is treated as missing.** During the grace period a malformed `X-Nexus-Api-Version` is accepted and logged, exactly like an absent header; once the header becomes required it is rejected the same way. Send a clean `major.minor.patch` tag (an optional leading `v`).
* **CORS preflight and WebSocket handshakes are never gated.** `OPTIONS` preflight and WebSocket upgrade handshakes are exempt — a browser cannot attach the header to either — so the gate never blocks them.
* **Discovery routes are never gated.** `/metadata`, `/openapi.json`, `/llms.txt`, and the `/.well-known/*` documents stay reachable at any version, so a stale client can always fetch what it needs to self-heal.

## Discovering the current version

The current minimum and latest versions are published at an unauthenticated metadata endpoint, so clients and agents can read the threshold without scraping docs:

```
GET /metadata
```

```json
{
  "api_version": {
    "header": "x-nexus-api-version",
    "min_supported": "0.6.0",
    "current": "0.6.2",
    "deprecated_below": null,
    "sunset": null,
    "spec_url": "https://github.com/nexus-xyz/nexus-exchange-api/releases",
    "docs_url": "https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning",
    "policy": "pre-1.0: minimum-supported version may advance until GA; missing version header allowed during grace mode"
  }
}
```

`/metadata` is always reachable regardless of the version you send — otherwise an out-of-date client could never learn the value it needs to upgrade.

## Recommended client pattern

1. Pin your client to a released spec version and send it in `X-Nexus-Api-Version`.
2. On a `426 api_version_unsupported`, read `spec_url` from the body (or `GET /metadata`), regenerate against a version `>= min_supported`, and retry.
3. Watch for `Deprecation` / `Sunset` response headers and upgrade before the sunset date.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.