# Versioning

Source: https://kirora.io/docs/api/reference/versioning

Learn what /v1 guarantees and how additive changes are signalled.

The public API lives under `/v1`. Three other surfaces are supported, each defined by
its own guide and not by this one:

- **`/segment/v1/*`**, the endpoints a Segment library or destination posts to. See
  [Sending data from Segment](https://kirora.io/docs/api/segment).
- **`/mcp`**, the MCP server for AI assistants. See [Agents](https://kirora.io/docs/api/agents).
- **The push `trackingUrl`**, the signed address a device reports a tap to. See
  [Push notifications](https://kirora.io/docs/api/push).

Anything else outside `/v1` is internal — the dashboard's own routes,
hosted pages, other tracking redirects — and is not a contract. It is left out of the
reference so it cannot be mistaken for one.

## What `/v1` guarantees

The guarantees below apply from general availability. Until then the contract can still
change.

From general availability, while `/v1` exists, none of the following will change:

- A path or HTTP method is not removed or repurposed.
- A field is not removed from a response, nor its type narrowed.
- A request field that was optional does not become required.
- An `operationId` does not change. These are the stable identifiers for issues,
  changelogs and reference pages, so renaming one breaks inbound links.
- An error `code` does not change meaning, and a code is not removed.
- The response envelope (`data` / `meta` / `error`) does not change shape.
- Pagination stays cursor-based.

## What can change without notice

These are **additive** and a client must tolerate them:

- **New endpoints and new tags.**
- **New fields in responses.** Do not use strict deserialisation that fails on unknown
  fields — this is the single most common way an SDK breaks on a routine release.
- **New optional request fields.**
- **New values in an enum**, including new error codes. Handle an unrecognised `code` by
  falling back to a generic error carrying the raw string rather than throwing.
- **New webhook event types**, which a `*` subscription will begin receiving.
- **Wording of `message` fields and documentation prose.** Branch on `code`, never on
  `message`.

Rate limits, and the exact numbers behind them, are deployment configuration rather than
contract. Read `Retry-After`.

## Explicitly not contract

- The **cursor format**. Opaque; see [Pagination](https://kirora.io/docs/api/reference/pagination).
- The **key format** beyond the `kirora_` prefix.
- Field **ordering** in JSON objects.
- Anything reachable only outside `/v1`.

## How a breaking change would happen

By introducing `/v2` alongside `/v1`, not by changing `/v1` underneath its users. Both
would run during a migration window announced in advance: the old surface stops taking
new users rather than changing behaviour for existing ones.

Treat every published operation as stable.

## Building a client that survives releases

1. **Deserialise permissively.** Ignore unknown fields; never fail on them.
2. **Treat enums as open.** A future `status` or `code` value must not crash a client.
3. **Take API changes deliberately.** Read the [changelog](https://kirora.io/docs/api/changelog) before
   upgrading a client, so a contract change is something you review.
4. **Do not depend on field order, cursor contents, or message wording.**
5. **Make the base URL configurable**, so tests can point at a mock server.

## Next steps

- [Errors](https://kirora.io/docs/api/reference/errors) — treat unknown codes as open
- [Pagination](https://kirora.io/docs/api/reference/pagination) — cursors are opaque
- [Webhooks](https://kirora.io/docs/api/webhooks) — event payloads and what may be added