Versioning

neolife runs a single, dated API version and evolves it additively — so an integration you build today keeps working. This page covers how to pin it, how to tell what you're talking to, and what "additive" guarantees you in practice.

The dated version#

The API version is a date: 2026-07-05. It's the version the OpenAPI spec declares, and it's what every response advertises back to you (see below). There's one live version at a time, and it moves forward only in backwards-compatible ways.

Pin the /v1 prefix#

Paths are served both unversioned and under a stable /v1 prefix — they resolve to the same handler, so /v1/orders and /orders are identical:

curl https://api.neolife.health/v1/orders \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

Prefer /v1/* in production code. It's the stable, explicit surface: if a future major version ever ships, it mounts under its own prefix (/v2/*), and your pinned /v1 traffic keeps hitting the version you built against. The SDKs target /v1 for you.

Read the Neolife-Version header#

Every response carries a Neolife-Version header with the dated version that served it:

curl -sD - -o /dev/null https://api.neolife.health/v1/orders \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" | grep -i neolife-version
# Neolife-Version: 2026-07-05

Log it. If you ever need to reproduce or report behavior, the version that served the request is right there in the headers alongside your X-Request-Id.

The spec is the source of truth#

The route surface, methods, auth, and schemas are generated from the running API and published as an OpenAPI 3.1 document. That document — not this site — is canonical for the exact shape of every request and response:

• Machine-readable spec: /openapi.json
• Interactive reference: /docs

Because it's generated from the live surface, it can't drift from what the API actually does. Point your own tooling at it — SDK generators, Postman, contract tests, or an MCP client — and you're always working from ground truth.

What "additive" means#

Within a dated version, changes are strictly additive. You can rely on these guarantees:

• New endpoints may appear.
• New optional request fields may be added — never new required ones on an existing operation.
• New response fields may be added, so tolerate unknown fields: parse defensively and ignore what you don't recognize.
• New enum values may appear over time (for example, new order or event statuses). Handle an unrecognized value gracefully rather than treating it as an error.

What we will not do inside a version: remove or rename a field, change a field's type, tighten validation on an existing request, or repurpose an existing status. Those are breaking changes, and they only ever land behind a new major prefix — never silently under /v1.

Practical guidance#

• Pin /v1 in production and target the SDKs at it.
• Parse tolerantly — extra response fields and new enum values are expected, not exceptional.
• Generate from the spec rather than hand-modeling payloads, so additive changes flow in for free.
• Keep an eye on the changelog for what's been added.

Related#

• API reference — base URL, resources, errors, rate limits.
• Errors — the stable error shape and status codes.
• Idempotency — safe retries for every mutation.
• Changelog — what's changed, newest first.