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

# Versioning

The API is versioned by date. A version fixes the shape of every request and response, so a version you build against does not change under you.

You choose one in two ways, and they behave differently: a **header** on a single request, or a **pin** on your account.

## The header

Send `X-Api-Version` with the version you want, on every request:

```
X-Api-Version: 2026-06-01
```

It applies to that request alone, overrides whatever your account defaults to, and is the way to be certain which shape you get.

<Warning>
  An unrecognised or mistyped value is refused with a `400` and `code: "invalid_api_version"`, naming the versions that are accepted. The API never quietly falls back to a different shape when it does not recognise the value you sent.
</Warning>

## The pin

Pinning sets your account's default, so calls without the header use it:

**[Pin account to a version](/api-reference/versioning/pin-account-to-a-version)**

Both the previous and the new version come back, so you can confirm the move happened.

<Warning>
  **A pin only moves forward.** Pinning to a version older than your account's current default is refused. The header is exempt from that rule, so it stays available for reading an older shape without changing anything stored.
</Warning>

## Which to use

**Send the header on every request.** It costs nothing, it is unambiguous, and it survives your account being pinned by someone else later.

**Pin as well** once you are settled on a version and want calls that omit the header to behave. Pinning does not replace the header — it decides what happens when the header is absent.

## What a version fixes

A version fixes shapes, not behaviour you can see from outside. Two versions can return the same field with a different set of values, or wrap the same rows differently.

Where a value set differs by version, the values page for that resource shows both, and the version selector at the top of these docs decides which reference you are reading.

## More versions exist than are documented

The API accepts versions this documentation does not cover, and the `400` above names them all. Those are there so accounts pinned to them keep working — they are not choices to make.

**Build against a documented version.** If your account defaults to one that is not documented, send the header rather than working from a reference that does not describe what you will receive.