> ## 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

> Send the X-Api-Version header on every request, then pin your account to lock in a schema version.

The Kira API is versioned by date. This documentation covers version `2026-04-14` — the version we recommend you integrate against and pin to. You select a version per request with the `X-Api-Version` header, or you can **pin** your account so that version becomes its default.

<Info>
  Two API versions are documented: `2026-04-14` (recommended — the default view) and `2026-06-01` (latest, which returns the [itemized quotation response](/guides/itemized-quotations) and the raw virtual-account `status` enum). Use the version selector at the top of these docs to switch between them.

  The backend additionally supports an intermediate version, **`2026-05-28`**, which some accounts (provisioned late May–early June 2026) are pinned to by default. It is not separately documented: `2026-05-28` behaves like `2026-06-01` except quotations still return the pre-itemized shape — in particular it already uses the raw virtual-account `status` enum. If your account default reads `2026-05-28`, use the `2026-06-01` reference for virtual-account statuses, or send `X-Api-Version` to select a documented version per request.
</Info>

## How the API picks a version

For each request, Kira resolves which schema version to apply in this order:

1. **The `X-Api-Version` request header**, when present — it always wins, even over a pinned account default.
2. **Your account's pinned version**, once you have called `POST /v1/versioning/upgrade` (see below).
3. **A baseline default** otherwise, which may be older than the version documented here.

Because of step 3, send `X-Api-Version: 2026-04-14` on **every** request until you pin, so you always get the schema documented on this site.

An unsupported or mistyped `X-Api-Version` value is rejected with `400 { "code": "invalid_api_version" }` listing the supported versions — the API never silently falls back to a different schema for an unrecognized header value.

## Send the version header

Until your account is pinned, send `X-Api-Version: 2026-04-14` on **every** request alongside your auth headers. This tells the API which schema version to use.

```bash theme={null}
curl https://api.balampay.com/sandbox/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $KIRA_API_KEY" \
  -H "X-Api-Version: 2026-04-14" \
  -H "Content-Type: application/json"
```

<Note>
  See [Authentication](/guides/authentication) for how to obtain `$ACCESS_TOKEN` and `$KIRA_API_KEY`.
</Note>

## Pin your account once

Call `POST /v1/versioning/upgrade` once with a `target_version` of `2026-04-14`. This locks your account's default to the documented schema (`2026-04-14`). The call is **idempotent** — running it again with the same target version is safe.

```bash theme={null}
curl https://api.balampay.com/sandbox/v1/versioning/upgrade \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $KIRA_API_KEY" \
  -H "X-Api-Version: 2026-04-14" \
  -H "Content-Type: application/json" \
  -d '{
    "target_version": "2026-04-14"
  }'
```

Upgrades are **forward-only**: you can move your pin to a newer version, but the API rejects a `target_version` older than your current pin with `400 "Cannot downgrade API version from '<current>' to '<target>'. Upgrades are forward-only. To use an older documented version per-request, send the X-Api-Version header — it is exempt from this rule."`. A successful call returns your `previous_version` and `current_version`.

<Note>
  Some accounts default to a version **newer** than `2026-04-14` (for example, partner-provisioned accounts). Because pins are forward-only, calling `POST /v1/versioning/upgrade` with `target_version: "2026-04-14"` on such an account returns that `400` — there is no self-serve downgrade. The `X-Api-Version` header is **exempt** from the forward-only rule, so it is always the escape hatch: send `X-Api-Version: 2026-04-14` on each request to get the documented schema regardless of your account default, with no `400` and no change to your stored pin.
</Note>

After pinning, the `X-Api-Version` header becomes **optional** on subsequent requests — your account default is the pinned version. You can still send the header to override it on a per-request basis.

## Status vocabulary depends on the version

The status values you see in responses and webhooks follow the **pinned version's** vocabulary. For example, virtual-account `status` uses the KYB-style mapping (`approved` / `rfi` / `declined`) on the `2026-04-14` pin, but the raw internal enum (`pending` / `activating` / `active` / `failed` / `deactivated`) on the `2026-06-01` pin.

<Warning>
  Casing and status vocabulary vary across surfaces and versions. Always compare statuses **case-insensitively**, and parse the response shape rather than assuming a fixed vocabulary. See [State machines](/guides/state-machines) and [Known limitations & quirks](/guides/known-limitations) for the full picture.
</Warning>