Skip to main content
The CollectiveX Health Partner API gives your product access to a grounded, peer-reviewed women’s-health research corpus. Every answer includes inline citations from real papers; the API refuses to answer when the corpus lacks strong evidence.

​
Two ways to use it

There are two ways to use the API. Pick whichever matches your integration. (A third, asynchronous way — submit the same question as a job and poll for the answer — is covered in Async jobs.)

Ask a question

POST /v1/query — one-shot. Send a single question, get one grounded JSON answer back. Stateless: no session, no setup, no history to manage.

Have a conversation

POST /v1/chat — multi-turn. Back-and-forth with streaming responses by default, or synchronous with stream: false.
Full request and response schemas live in the API Reference tab, generated from our OpenAPI spec — the same file you can download at api.collectivex.health/openapi/v1-chat.yaml to generate a typed client.

​
When to pick /v1/query

Most partner integrations don’t need a conversation at all — just a question and a grounded answer. /v1/query is the simplest way in: send one question, get back one JSON response, done.
  • Snapshot insights — daily, weekly, or on-demand recommendations
  • Embedded ask-widgets — drop a research-search box on a content site
  • Claude Skills, MCP tools, agent tool-calls — one call, one cited answer
  • Slack / Discord slash commands — /research <question> → answer + sources
  • Background batch generation — content calendars, email digests, alerts
  • Voice assistant integrations — single utterance → single grounded answer
Because each call is independent, you can also cache by query hash (same question, same answer, skip the call), retry safely, and fan out many different questions in parallel within your per-key rate budget.

​
When to pick /v1/chat

A chat widget, an assistant thread, or any flow with follow-ups where the next question references the prior one (“is it different?”, “what about HRT?”). Streaming by default so users see text appear as it’s generated; send stream: false to wait and get one JSON blob back. Answers are retrieval-grounded and fully generated per request, so a complete answer takes roughly 14–23 seconds end to end. Streaming puts first words on screen at about 9 seconds (p50) instead of an ~18 second blank wait — prefer it for anything user-facing.

​
Safety behavior, on every endpoint

Two behaviors are uniform across /v1/query and /v1/chat and your integration must handle both:
  • Deferral — when the corpus lacks strong evidence for a query, the API returns a deferral object instead of an answer (answer is an empty string, citations an empty array). Present the originalQuery back to the user and do not synthesize an answer from training data.
  • Crisis — when a safety classifier fires before retrieval (self-harm, acute symptoms, IPV), the API returns a crisis object with region-appropriate resources. Show the resources verbatim — do not reorder, summarise, or omit fields — and route the user away from research framing.
See Errors and rate limits for the error envelope, and Structured answers for how these outcomes surface in the beta structured response format.

​
Get a key

All requests require a partner API key. To request one, email partners@collectivex.health. Keys are server-side only — see Authentication before you write any client code.