CollectiveX Health Partner API — Developer Docs

Hand-written integration guide for the CollectiveX Health partner API (/v1/oura/* and future routes). Complements the auto-generated OpenAPI reference hosted at partnerdocs.collectivex.health.

Audience: engineers integrating their health-data product with the CollectiveX Health recommendation engine.

Start here

1. Getting started — copy-paste cURL that returns HTTP 200. Do this first.
2. Authentication — API key format, rotation, revocation.
3. Request / response reference — full body contract, enum tables, response fields, suppression semantics.

When you hit a bug

4. Errors — per-status walkthrough (400 / 401 / 403 / 422 / 429 / 502) with retry guidance.
5. Idempotency — safe retries and the 5-minute cache.
6. Rate limits — 30 req/min per key, exponential backoff with jitter.

Lifecycle

7. Changelog — version history + Sunset deprecation policy.
8. Support — contact, response times, severity ladder.

Contract highlights

• Pure-metrics-only. Send raw scientific measurements (HRV in ms, heart rate in bpm, sleep stages in seconds). Aggregate scores (*_balance, score) are ignored if present. See request-response-reference.md.
• Day-zero integration. Oura's first production request arrives through the Zuplo gateway — no "dual-running" window, no direct origin URL ever exposed.
• 30 req/min per key. Hard ceiling. HTTP 429 on breach with Retry-After.
• Idempotent within 5 minutes. Re-sending the same (client_id, request_id) pair within 5 minutes returns the original response from cache without re-processing.
• EU residency. All gateway and origin infrastructure runs in EU regions. Request bodies are not logged at the gateway.

The auto-generated reference

These hand-written docs cover the "why", the "when it goes wrong", and the semantic details the OpenAPI spec can't express. For the formal machine-readable schema (route list, request/response JSON Schema, status codes), see partnerdocs.collectivex.health/api. It is kept in sync with the live gateway config on every change.

If something in these docs contradicts the auto-generated reference, the auto-generated reference wins for schema shape — tell support so we can reconcile.