Changelog

Version history for the CollectiveX Health partner API.

Major (2.0.0): breaking changes — partners must update.
Minor (1.1.0): additive changes, backwards-compatible.
Patch (1.0.1): bug fixes, no contract change.

Version applies to the OpenAPI contract at partnerdocs.collectivex.health/api. The model_version field in response bodies is a separate opaque string — don't parse it; it changes on recommendation-engine updates that don't affect the wire contract.

v0.1.0 — 2026-04-28 (sandbox alpha)

Initial public release. Sandbox only — prod cutover is a later milestone.

Endpoints

POST /v1/oura/recommendation — cycle-aware wellness recommendation grounded in raw Oura biomarkers (HRV, heart rate, sleep stages, VO₂ max, readiness, SpO₂).

Contract

Authentication via Zuplo-minted API keys (ApiKey / Bearer header).
Rate limit: 30 req/min per key.
Idempotency: 5-minute Redis cache on (client_id, request_id).
Pure-metrics-only body contract — vendor aggregate scores silently dropped.
Two safety modes: strict (rejects clinical queries) / permissive (processes all wellness queries).
Two response shapes: Shape A (explicit query → recommendation primary) / Shape B (implicit trigger → suggested_questions primary).
Three suppression reasons: below_platform_threshold, below_client_threshold, insufficient_signal.

Envelope shapes

200, 422, 500, 502: flat {request_id, trace_id, error: {code, message, details}} envelope (success responses have the recommendation shape; error responses use the flat envelope for errors).
401, 403 (gateway + consent): FastAPI-default {detail: "<reason>"} shape.
429: Zuplo-emitted body with Retry-After header.

Deprecation policy

Fields and endpoints are never removed without a deprecation window.

How we signal deprecation

Documentation — the deprecated field or endpoint is marked in these docs and in the auto-generated OpenAPI reference.
Sunset header — when a response returns content whose schema is scheduled for removal, we include a Sunset HTTP response header with the planned removal date in HTTP-date format: Sunset: Sat, 31 Aug 2026 00:00:00 GMT
Changelog entry — an entry in this file announcing the deprecation, the planned removal date, and the replacement path (if any).

Minimum notice period

30 calendar days between the first Sunset-header emission and the actual removal. We aim for 90 days for anything load-bearing.

What counts as a breaking change (major version bump required)

Removing a field from a request or response body.
Changing a field's type (int → string, enum contraction).
Removing an endpoint.
Changing an error code's HTTP status.

What does NOT count as a breaking change (minor bump ok)

Adding a new optional field to a request.
Adding a new field to a response body (you're expected to ignore unknown fields).
Adding a new value to an enum (you're expected to handle unknown values gracefully).
Adding a new endpoint.
Adding a new error code within an existing HTTP status.
Performance improvements, bug fixes.

Your side of the contract

Forward-compatibility requires partner cooperation:

Ignore unknown fields in response bodies. We reserve the right to add non-breaking fields (e.g. warnings, new citation metadata). Your parser must not fail on unknown keys.
Don't assume enum closedness. We may add cycle_phase values (e.g. unknown) without a major bump, but we'll document it in the changelog. Handle unknown enums gracefully (fall back to a safe default in your UI).
Honor Sunset headers. If you see one, plan the migration before the date.

Versioning anti-patterns (what we won't do)

No URL versioning for trivial changes. We won't bump to /v2/oura/... for an additive field. /v1/ is the stable path; non-breaking changes ship in place.
No silent contract changes. Anything that could break partner code gets a major version + a Sunset window. If you suspect silent drift, raise it in support.
No "v1.1.0" URL prefixes. Minor/patch versions are documentation-only — they don't affect the route path.