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

# Versioning

How Vantage API versions work: choosing a version per request, your account's pinned version, versioned webhooks, and upgrading.

## Versions are dates

Each Vantage API version is named by a date, such as `2026-10-15`. A breaking change ships under a new date. Additive changes, such as a new field or a new endpoint, land in every version. The [changelog](/vantage-api/changelog.md) lists every version and what changed in it.

## Choosing a version

Each request is served in one version, picked in this order:

1. The `X-Terra-Version` header on the request, if you send one.
2. Your account's pinned version.

Your account is pinned to the latest version on its first request, so new integrations always start on the latest version and keep it until you upgrade.

Every response carries an `X-Terra-Version` header stating the version it was served in.

```bash
curl 'https://vantage-sandbox.tryterra.co/api/v1/products/1' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY' \
  -H 'X-Terra-Version: 2026-10-15'
```

An unknown version returns `400` with code `invalid_api_version`. The `detail` lists the supported versions. See [Errors](/vantage-api/errors.md).

## Webhooks

Webhook deliveries use your account's pinned version. The request header does not apply to them. Each delivery carries the version it was rendered in as an `X-Terra-Version` header.

If you process deliveries asynchronously, store the `X-Terra-Version` header with the body, so the worker knows which shape it is reading. See [Webhooks](/vantage-api/webhooks.md).

## Upgrading

Your pinned version is shown next to the Test mode toggle in the Vantage dashboard. When a newer version exists, you can upgrade from there:

1. Read the [changelog](/vantage-api/changelog.md) for every version between yours and the latest.
2. Send `X-Terra-Version` with the new date on individual requests, and check your code handles the new shape.
3. Update your webhook handler to accept the new shape, using the `X-Terra-Version` header on each delivery to tell the two apart.
4. Select **Upgrade** in the dashboard's API version menu.

Once the pin changes, requests without the header and all webhook deliveries use the new version. The pin applies to Test mode and Production together.

If something breaks after an upgrade, switch back under **Older versions** in the same menu.