API reference

Versioning

Versioning is two-level (Stripe-style): a major version in the URL path and an optional date-based minor pinned with an Accept-Version header.

URL major#

The major version lives in the path, for example /v1. A new major version is a new path prefix and is reserved for breaking changes. The error envelope itself (its field names and shape) is frozen at v1.0; changing it would require a v2 of the API and a coexistence window.

Accept-Version (minor)#

Within a major version, behavior is pinned by a date-based minor. Send an optional Accept-Versionheader with a date to lock in that minor's behavior. Omit it to get the current default minor. Additive changes (like a new error code) are minor-version changes; renaming or removing a code is a major-version change.

bash

curl https://api.lirovo.ai/v1/health \
  -H "Accept-Version: 2026-05-23"
# Response carries: X-Lirovo-Api-Version: 2026-05-23

Echoed version#

Every response echoes the resolved version in the X-Lirovo-Api-Version header, so you can confirm exactly which minor served your request.

Deprecation window#

Removing or renaming a stable field or error code is a breaking change with a deprecation window of at least 12 months, during which both the old and new behaviors coexist. The old form is marked as deprecated for the duration so clients can migrate before it is withdrawn.

Pin in production

Set Accept-Version to a fixed date in production code so a new default minor cannot silently change behavior. Read X-Lirovo-Api-Version on the response to verify the pin took effect.