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

# API versioning

> Date-based versions. Pin one, and the response shape stays frozen — even as we evolve the API.

Kynva uses **date-based versioning** (same approach as Stripe, Anthropic). Each calendar release date is a frozen contract: same fields, same types, same enum values, forever.

## How to pin a version

Send the `X-API-Version` header on every request:

```http theme={null}
X-API-Version: 2026-01-01
```

If you don't send the header, we default to the **oldest still-supported version** — currently `2026-01-01`. We do this on purpose: silence is safer than guessing.

## Supported versions

| Version      | Status      | Notes                 |
| ------------ | ----------- | --------------------- |
| `2026-01-01` | **Current** | First public release. |

When we release a new version we'll publish:

* A migration guide in the [Changelog](/changelog/2026).
* An automated diff highlighting renamed/removed fields.
* An overlap window of at least 6 months before the old version is retired.

## What can change between versions

Breaking changes (require a version bump):

* Removing or renaming a field
* Changing the type of a field
* Removing or renaming an enum value
* Changing required vs optional
* Changing default values
* Changing the meaning of an error code

Non-breaking changes (ship in any version):

* Adding new fields
* Adding new enum values
* Adding new endpoints
* Adding new optional headers
* Loosening validation (e.g., accepting more formats)

## Discover what's available

```http theme={null}
GET https://api.kynva.ai/api/v1/facade/api-versions
```

Returns:

```json theme={null}
{
  "current_version": "2026-01-01",
  "supported_versions": ["2026-01-01"],
  "default_version": "2026-01-01",
  "deprecated_versions": []
}
```

## What happens if I send a bad version

```http theme={null}
HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "API_VERSION_UNSUPPORTED",
    "message": "X-API-Version '2025-06-01' is not supported. See /api/v1/facade/api-versions."
  }
}
```

See [`API_VERSION_UNSUPPORTED`](/errors/codes#api-version-unsupported) for recovery.