> 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, upgrading, and the changelog.

## Versions are dates

Each Vantage API version is named by a date, such as `2026-10-01`. A breaking change ships under a new date. Additive changes, such as a new field or a new endpoint, land in every version.

## 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, if it has one.
3. Otherwise, the latest version.

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-01'
```

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, or the latest version if your account has no pin. 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

Most accounts have no pin and always receive the latest version. If your account is pinned to an older version:

1. Send `X-Terra-Version` with the new date on individual requests, and check your code handles the new shape.
2. Update your webhook handler to accept the new shape, using the `X-Terra-Version` header on each delivery to tell the two apart.
3. Ask Terra to move or remove your account's pin. There is no self-serve setting yet.

Once the pin changes, requests without the header and all webhook deliveries use the new version.

## Changelog

### `2026-10-01`

Catalogue variants carry typed fields. See [Core concepts](/vantage-api/core-concepts.md).

* Variant `variant_name` is renamed to `name`.
* Variant `descriptive_attrs_override` is replaced by `description`.
* Variant `variant_defining_attrs` is replaced by `turnaround_days` and `collection_method`.
* Variant `variant_availability` is replaced by `availability`, a string: `unknown`, `in_stock` or `out_of_stock`.
* Variant `requires_activation` is added.
* Product `model_descriptive_attrs` is removed. Its collection method is now `collection_method` on each variant.
* Product `availability` is a string instead of an integer.
* Webhook payloads are unchanged.

### `2026-09-27`

Baseline. Catalogue variants carry attribute bags and integer availability.