Skip to main content
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.
Two API versions are documented: 2026-04-14 (recommended — the default view) and 2026-06-01 (latest, which returns the itemized quotation response 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.

​
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.
See Authentication for how to obtain $ACCESS_TOKEN and $KIRA_API_KEY.

​
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.
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.
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.
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.
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 and Known limitations & quirks for the full picture.