Have a conversation — streaming or sync
Dual-mode endpoint. By default (stream omitted or true) returns a streaming
UIMessage SSE response compatible with the Vercel AI SDK useChat hook. Send
stream: false to receive a synchronous JSON response (the SyncResponse shape)
suited for Claude Skills, MCP tool calls, and agent pipelines.
Server-to-server (the only supported pattern for web), or
native-mobile-direct via a short-lived session token minted by
your backend through POST /v1/session-tokens (native mobile only,
not browser/JS — see “API keys” above). Never embed your long-lived key in any client,
browser or mobile.
Rate limits are communicated via X-RateLimit-* headers on every
response and are shared with /v1/query per API key
(see “Rate limits” above). When a 429 is returned, honour
Retry-After before retrying.
Authorizations
Bearer token used by every /v1/* endpoint. Two kinds of key work here:
- Long-lived partner key (
cxh_pk_live_*) — issued by CollectiveX Health (contact partners@collectivex.health). Keep it server-side only — never expose it in client bundles or mobile app code. This rule is absolute and does not change for any endpoint. - Short-lived session key — minted server-side via
POST /v1/session-tokensfrom a long-lived key. Safe to hand to a native mobile client only — not a browser or other JavaScript context, see "API keys" in the description above. It's scoped to/v1/queryand/v1/chatonly, expires in at most 60 minutes, and can't mint further session keys.POST /v1/session-tokensitself only ever accepts the long-lived key.
Body
Request body for POST /v1/chat. Uses additionalProperties: false (mirrors Zod .strict() on the server). Any unknown field returns 400 invalid_request naming the offending field. Retrieval tuning knobs (topK, rerank, rerankModel, rerankLimit, minScore, filter, mode, includeRelationships) are intentionally stripped — we curate retrieval; partners don't tune.
Conversation history as AI SDK v6 UIMessage objects. Only the last 10 messages are used (matched to the internal pipeline's slice cap).
1Show child attributes
Show child attributes
When true (default), returns text/event-stream SSE. When false, returns application/json SyncResponse. Cannot be combined with other streaming negotiation headers.
Latency note: sync mode waits for the complete generation before the first response byte (~18s p50 measured in production); streaming delivers the first answer tokens at roughly half that (~9s p50). Prefer streaming for anything user-facing — see "Latency: prefer streaming" in the introduction.
Response
OK. Content type depends on the stream field in the request body:
stream: true(default):text/event-stream— AI SDK v6 UIMessage SSE protocol.stream: false:application/json— SyncResponse flat envelope.
AI SDK v6 UIMessage stream protocol. The response header
x-vercel-ai-ui-message-stream: v1 is always present on streaming responses.
Each line is a server-sent event of the form data: <json>\n\n.
Partner-visible chunk types (inclusion list — all others are filtered):
start/finish/start-step/finish-step: control flow bracketstext-start/text-delta/text-end: streamed answer textdata-sources: citation array (one chunk per response)data-deferral: emitted when corpus lacks strong evidence (no answer)data-crisis: emitted when a safety classifier fires before retrievalerror/abort: error propagation
See https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol for full chunk format.