> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collectivex.health/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Grounded answers from a peer-reviewed women's-health research corpus, with inline citations on every answer.

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](https://docs.collectivex.health/async-jobs.md).)

> **[Ask a question](https://docs.collectivex.health/quickstart.md)**
>
> `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](https://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](https://docs.collectivex.health/errors-and-rate-limits.md) for the error envelope,
and [Structured answers](https://docs.collectivex.health/structured-answers.md) 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](mailto:partners@collectivex.health). Keys are
**server-side only** — see [Authentication](https://docs.collectivex.health/authentication.md) before you write
any client code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.