Quickstart

The fastest way in is POST /v1/query: send one question, get back one JSON response, done. The endpoint is stateless — no session, no setup, no history to manage.

Run this from a server or your terminal, never from browser code — see Authentication for why the key is server-side only.

1. Ask a question

curl -sS -X POST https://api.collectivex.health/v1/query \
  -H "Authorization: Bearer $CXH_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "question": "What does the research say about magnesium for perimenopause sleep?"
  }'

2. Read the response

What comes back (SyncResponse, abbreviated):

interface SyncResponse {
  request_id: string;          // UUID — use for support correlation
  answer: string;              // empty string on deferral or crisis
  citations: Citation[];       // empty array on deferral or crisis
  deferral?: { originalQuery: string };  // corpus lacked strong evidence
  crisis?: { category, locale, originalQuery, resources };  // safety classifier fired
  error?: { message: string }; // generic sanitized failure message (v1.1)
}

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "answer": "Magnesium supplementation has been associated with modest improvements in sleep quality during perimenopause...",
  "citations": [
    {
      "id": "CXH-00835",
      "score": 0.92,
      "text": "Transdermal estradiol was associated with significant reductions...",
      "metadata": { "doi": "10.1093/humrep/dead156", "year": "2023" }
    }
  ]
}

3. Handle all three outcomes

A response is not always a grounded answer. Your integration must handle the deferral and crisis short-circuits too:

Deferral — answer is an empty string, citations an empty array, and deferral.originalQuery is set. The corpus lacks strong evidence for the query. Present the originalQuery back to the user and do not synthesize an answer from training data.
Crisis — answer is an empty string, citations an empty array, and crisis carries a category (self-harm, acute-symptom, or ipv), a locale, the originalQuery, and a resources array. Show the resources verbatim and route the user away from research framing. Never omit or reorder resources.

Citations only ever come from the citations array — never fabricate or paraphrase a citation that is not in it.

Already building `/v1/chat` request bodies?

/v1/query also accepts a single-element messages array in place of question, for continuity with callers already building /v1/chat bodies:

curl -sS -X POST https://api.collectivex.health/v1/query \
  -H "Authorization: Bearer $CXH_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "messages": [
      {
        "id": "msg_smoke_1",
        "role": "user",
        "parts": [{ "type": "text", "text": "How does luteal-phase progesterone affect sleep?" }]
      }
    ]
  }'

Unlike /v1/chat, this array must contain exactly one message with role user — /v1/query has no multi-turn concept. Sending more than one message, or a different role, returns 400 invalid_request. Exactly one of question or messages is required — not both.

Next steps

Machine-readable output: Structured answers (beta)
What can go wrong: Errors and rate limits
Conversations and streaming: see the API Reference tab for /v1/chat

Getting Started

Features

Reference

1. Ask a question

2. Read the response

3. Handle all three outcomes

Already building `/v1/chat` request bodies?

Next steps

​1. Ask a question

​2. Read the response

​3. Handle all three outcomes

​Already building /v1/chat request bodies?

​Next steps

1. Ask a question

2. Read the response

3. Handle all three outcomes

Already building `/v1/chat` request bodies?

Next steps