> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vantr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API versioning

> Pin a dated release with the X-API-Version header so your integration never breaks when the API evolves.

# API versioning

The `/v2` base URL is permanent. Behavior is versioned by **release date** — when we ship a breaking change, it goes out as a new dated version, and your integration keeps receiving the version it was built against until you choose to upgrade.

## How to pin a version

Send the `X-API-Version` header with a release date (`YYYY-MM-DD`):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.vantr.ai/v2/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Version: 2026-06-09"
```

* **Omit the header** and you get the **latest** release. Good for trying things out; pin a date before you ship.
* Every response echoes the resolved version back in the `X-API-Version` response header, so you can confirm exactly which version served the request.

<Note>
  We recommend pinning an explicit `X-API-Version` in production. Without it, your integration silently moves to the latest release whenever we publish one, which may include breaking changes.
</Note>

## Unknown or malformed versions

A version that isn't a published release — a typo, a future date, or a retired version — is rejected rather than silently changed:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": false,
  "code": "unsupported_api_version",
  "message": "Unknown API version \"2099-01-01\". Supported versions: 2026-06-09. Omit X-API-Version to use the latest (2026-06-09)."
}
```

This returns `400 Bad Request`. It's deliberate: a mistyped version should fail loudly, never upgrade you by accident.

## How older versions keep working

Internally the API always runs the latest shape. When you pin an older release, the response is transformed back to the shape that release promised (and your request body is upgraded forward), so older integrations see no change in their contract. You only adopt new fields and behavior when you move your pinned date forward.

## Discover versions programmatically

`GET /v2/versions` returns the supported releases — no authentication required, so your setup or CI can check before pinning:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.vantr.ai/v2/versions
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": true,
  "header": "X-API-Version",
  "latest": "2026-06-09",
  "default": "2026-06-09",
  "versions": [
    { "version": "2026-06-09", "label": "Initial v2 release", "status": "current" }
  ]
}
```

## Released versions

| Version      | Status | Summary                                                                             |
| ------------ | ------ | ----------------------------------------------------------------------------------- |
| `2026-06-09` | Latest | First public v2 release: OAuth 2.0 access to catalog, orders, locations, and usage. |

Use the **version switcher** at the top of these docs to read the reference for a specific release. Each version's API reference reflects exactly the schema that version serves. New releases and their changes are recorded in the [changelog](/changelog).