CollectiveX Health Partner API — Developer Docs
Hand-written integration guide for the CollectiveX Health partner API (/v1/TENANT/* and future routes). Complements the auto-generated OpenAPI reference hosted at docs.collectivex.health.
Audience: engineers integrating their health-data product with the CollectiveX Health recommendation engine.
Conventions
These docs use TENANT as a placeholder for your tenant slug — the URL component CollectiveX assigns to your account. Ask your CollectiveX Health contact for your slug if you don't know it. Substitute it everywhere you see:
- URL paths —
/v1/TENANT/recommendation - JSON request body — top-level
"TENANT": { ... }key - Tenant identifier —
cxh-{sandbox|prod}-TENANT(returned by/v1/health/me, used in support tickets) - Scope strings —
v1.TENANT.recommendation(returned by/v1/health/me) - JSON-path references —
TENANT.sleep[0],TENANT.daily_readiness, etc.
In code samples we use $TENANT (bash), {TENANT} (Python f-strings), or ${TENANT} (JS template literals); export it alongside $CXH_API_KEY and $CXH_BASE_URL.
The auto-generated OpenAPI reference at /api shows the literal route, type names, and field names for the active partner deployment — use it as the wire-format ground truth and substitute the placeholder convention from these hand-written docs accordingly.
Start here
- Getting started — copy-paste cURL that returns HTTP 200. Do this first.
- Authentication — API key format, rotation, revocation.
- Request / response reference — full body contract, enum tables, response fields, suppression semantics.
When you hit a bug
- Errors — per-status walkthrough (400 / 401 / 403 / 422 / 429 / 502) with retry guidance.
- Idempotency — safe retries and the 5-minute cache.
- Rate limits — 30 req/min per key, exponential backoff with jitter.
Lifecycle
- Changelog — version history +
Sunsetdeprecation policy. - 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. - 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 docs.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.