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

# Versioning

> How KnoxCall versions its API: the /v1 path major plus the dated KnoxCall-Version header minor, what counts as a breaking change, and how to pin.

# Versioning

KnoxCall versions the API on two axes:

* **Major** — the URL path (`/v1`). It only changes for a wholesale redesign, and old majors
  keep working.
* **Minor** — a **dated revision** selected with the `KnoxCall-Version` request header
  (`YYYY-MM-DD`). This is the same model Stripe (`Stripe-Version`) and Anthropic
  (`anthropic-version`) use.

```bash theme={"dark"}
curl https://api.knoxcall.com/v1/routes \
  -H "Authorization: Bearer $KNOXCALL_ACCESS_TOKEN" \
  -H "KnoxCall-Version: 2026-08-05"
```

The current version is **`2026-08-05`**. Every response echoes the version that served it as a
`KnoxCall-Version` response header.

## Pinning

If you send no `KnoxCall-Version` header, the request runs against the **newest** version. To
insulate your integration from future breaking changes, **pin** the header to a dated version;
the official SDKs do this automatically, sending the version they were built against.

An unknown or malformed `KnoxCall-Version` is rejected:

```json theme={"dark"}
{
  "error": {
    "type": "invalid_api_version",
    "message": "Unknown KnoxCall-Version \"2099-12-31\". Supported versions: 2026-08-05.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

## What is (and isn't) a breaking change

We add fields, enum values, and endpoints **without** a new version — these are **not**
breaking, and your client must tolerate them:

* **Tolerate unknown fields.** Don't fail if a response grows a new property.
* **Tolerate new enum values** on fields you don't strictly switch over.
* **Don't depend on property order** or on the absence of a field.

A change that could break a conforming client — removing or renaming a field, changing a type,
changing a status code, tightening validation — ships under a **new dated version**. Your
pinned version keeps the old behaviour; you migrate on your own schedule by bumping the header.

## Changelog

Dated API changes are recorded in the [Changelog](/api-reference/changelog). Watch it for new
versions and the migration notes that accompany any breaking change.