Skip to main content
POST
cURL

Authorizations

x-api-key
string
header
required

API key for authentication. Contact support@verahealth.ai to obtain your API key.

Body

application/json

Request envelope for POST /api/chat/v3.

question
string
required

The clinical question to answer.

Minimum string length: 1
Example:

"What is the usual adult oral dose of amoxicillin for pneumonia?"

thread_id
string<uuid>

Continue an existing conversation. Pass the x-thread-id (or thread_id) of an earlier answer to ask a follow-up in that thread. Omit it to start a new thread. Only threads created with your partner account can be continued; any other id returns 404.

Example:

"3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e9f0a2b"

tools
enum<string>[]

Optional tools to enable for this request. Omitting the field and sending an empty array are equivalent: both leave every switchable tool off, and the agent answers with the always-on retrieval tools alone. There is no per-key default set. Duplicates are collapsed. An unknown id returns 400; an id your key is not provisioned for returns 403.

A tool you can switch on or off per request. Literature retrieval is always on and is not listed here: it cannot be disabled.

Available options:
drug,
medcalc,
patientHandout,
priorAuth
Example:
country
enum<string>

Jurisdiction of the clinician, ISO 3166-1 alpha-2. Only the jurisdictions whose national authority publishes in its own language are accepted, because only those change the answer. Case-insensitive. Omit it and no jurisdiction weighting is applied.

Available options:
FR,
IT
Example:

"FR"

stream
boolean
default:true

true (default) streams the AI SDK UI message stream. false returns a single JSON payload.

suggestions
boolean
default:false

Ask for three follow-up questions derived from the answer. With stream: false they arrive in the suggestions field of the JSON body; a streamed turn emits them as a data-suggestions event. Both lanes send them only when this is true. Off by default because they are a second model call made after the answer is already complete, and a request/response caller waits for it.

Response

When stream is true (default), the response is the AI SDK UI message stream (Content-Type: text/event-stream, x-vercel-ai-ui-message-stream: v1). Each frame is data: {JSON}\n\n with a top-level type, and the stream ends with data: [DONE]. See the agentic streaming guide.

When stream is false, the response is a single JSON payload returned once the answer is complete.

Both responses carry an x-vera-request-id header.

The response is of type string.