curl --request POST \
--url https://api.collectivex.health/v1/jobs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"question": "What does the research say about magnesium for perimenopause sleep?"
}
'{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"id": "8f14e45f-ceea-467e-adc0-7a1a6b5f6b28",
"job_type": "query",
"status": "queued",
"poll_url": "/v1/jobs/8f14e45f-ceea-467e-adc0-7a1a6b5f6b28",
"expires_at": "2026-09-11T13:00:00.000Z",
"created_at": "2026-09-11T12:00:00.000Z"
}Submit a question as an async job (asynchronous /v1/query)
Submit exactly the request body you would send to POST /v1/query
and get a job id back immediately, instead of waiting for the
grounded answer on an open connection. The answer is produced in
the background and read with GET /v1/jobs/{id} — see the “Async
jobs” tag description for the lifecycle, retention, and a polling
recipe.
Validation is identical to /v1/query, and happens now. The
body must contain exactly one of question or messages (one
user message), may set response_format, and may not contain
anything else. Every 400 this endpoint returns — unknown field,
both/neither shape, empty or whitespace-only question, a message
with a file part, a non-user role — is one /v1/query would
have returned for the same body. Nothing is accepted here only to
fail an hour of polling later. One extra rule applies only here:
the body is persisted and echoed back on every poll, so it is
capped at 32 KiB of JSON.
What runs, and when. On 202 the job is queued and starts
running immediately, in the background. It is the same
retrieval + safety + generation pipeline /v1/query uses, with the
same published tone and the same deferral/crisis behaviour — so
the eventual result is exactly the QueryResponse you would have
received synchronously. Expect the job to finish in the same
10–40 s a synchronous call takes; a job is never faster than the
sync call, it just doesn’t make you wait on the socket.
Metering. Submitting is one metered request against your
per-key budget (the same pool as /v1/query, /v1/chat, and
polling). The background execution is not metered again.
Server-to-server only, with your long-lived key. A session
token gets 403 forbidden here, exactly as on GET /v1/jobs/{id}.
Never embed your long-lived key in a client.
curl --request POST \
--url https://api.collectivex.health/v1/jobs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"question": "What does the research say about magnesium for perimenopause sleep?"
}
'{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"id": "8f14e45f-ceea-467e-adc0-7a1a6b5f6b28",
"job_type": "query",
"status": "queued",
"poll_url": "/v1/jobs/8f14e45f-ceea-467e-adc0-7a1a6b5f6b28",
"expires_at": "2026-09-11T13:00:00.000Z",
"created_at": "2026-09-11T12:00:00.000Z"
}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
- Option 1
- Option 2
Request body for POST /v1/query. Uses additionalProperties: false (mirrors
Zod .strict() on the server, matching ChatRequest's convention). Exactly
one of question or messages is required — not both. Retrieval tuning
knobs are intentionally not accepted here either, for the same reason as
/v1/chat: we curate retrieval, partners don't tune.
A single question, plain string. The preferred shape for /v1/query callers — no message envelope needed. Internally wrapped into a single-element UIMessage before being passed to the same pipeline that /v1/chat uses, so behavior is identical to sending that text as the sole message on /v1/chat.
1Single-element AI SDK v6 UIMessage array, provided for continuity with callers already building /v1/chat request bodies who want to switch endpoints with a minimal diff. 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 message with a different role, is a 400 invalid_request (use /v1/chat with stream:false instead if you need conversation history).
1 elementShow child attributes
Show child attributes
BETA. When omitted or "text", the response is byte-for-byte
the SyncResponse this endpoint has always returned — no behavior
change. When "structured", the response ADDS a structured_answer
field (machine-readable sections/claims/citations) alongside the
unchanged answer/citations fields; nothing is removed or
replaced. This field, and the shape it produces, may change in a
future minor version while in beta.
text, structured Response
Accepted. The job exists and is running in the background. Poll
poll_url (a path relative to the API base URL you called)
until status is terminal. Nothing about the answer is known
yet — this response deliberately carries no result.
202 body from POST /v1/jobs. A receipt, not a result: it tells
you where to poll and how long the job will be readable.
UUID minted for this submission. The job's background execution reuses it for tracing, so quote it to support.
The job's id. Use it with GET /v1/jobs/{id}.
Always query today — see JobResponse.job_type.
"query"
Always queued on the 202 — execution begins in the background immediately after this response is sent.
queued Path to poll, relative to the API base URL you called (e.g.
/v1/jobs/8f14e45f-…). Deliberately not an absolute URL: the
host you called is the host to poll.
"/v1/jobs/8f14e45f-ceea-467e-adc0-7a1a6b5f6b28"
When the job and its result stop being readable — one hour after submission. Fetch your result before then.
When the job was created.