Docs
kirora.ioGet started
VersioningMenu
On this page

API reference

Versioning

Updated

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.
  • /mcp, the MCP server for AI assistants. See Agents.
  • The push trackingUrl, the signed address a device reports a tap to. See Push notifications.

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.
  • 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 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