> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verahealth.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Ask the agent with a chosen tool set
> **Preview endpoint: integration testing only.** Access is granted under a written testing agreement and is enabled per API key. Request text is sent to the model provider and recorded in Vera's tracing system, and the endpoint carries no availability or stability commitment. Call it server to server: no CORS headers are sent, so a browser cannot read a cross-origin response, and your API key must never reach a browser.
Runs Vera's agentic engine and streams the answer along with the tool activity that produced it. The `tools` parameter selects which optional tools the agent may call, so a single integration can offer a different capability set at each step of a workflow. Omitting it is the same as sending an empty array: there is no per-key default set.
Literature retrieval is always on and is not part of `tools`, so a caller cannot disable the search every answer depends on. A request without `thread_id` starts a new thread, saved under your partner account, and its id comes back in the `x-thread-id` header. Send that id as `thread_id` to ask a follow-up: Vera answers the new question with the earlier turns of that thread in context, and saves it to the same thread. If a streamed connection drops, reconnect with [GET /api/chat/v3/threads/{threadId}/stream](/api-reference/v3/reconnect-to-an-agentic-stream), using the same id.
See the [tool guide](/docs/guides/agentic-tools) for the tool groups and the [agentic streaming guide](/docs/guides/agentic-streaming) for the event format, which is **not** the same as `/api/chat/v2`.
## OpenAPI
````yaml /docs/api-reference/openapi.json post /api/chat/v3
openapi: 3.1.0
info:
title: Vera Health API
version: 1.0.0
description: >-
Send medical questions and receive evidence-based answers with citations as
a Server-Sent Events stream.
contact:
name: Vera Health
url: https://www.verahealth.ai
servers:
- url: https://www.verahealth.ai
description: Production server
security:
- apiKeyAuth: []
tags:
- name: v2
description: >-
Send a medical question and receive an evidence-based answer as a
Server-Sent Events stream.
- name: v3
description: >-
Preview agentic endpoint. Runs Vera's tool-using agent and lets each
request choose which optional tool groups are available. Testing only.
- name: v1
description: Legacy v1 chat endpoint. New integrations should use v2.
paths:
/api/chat/v3:
post:
tags:
- v3
summary: Ask the agent with a chosen tool set
description: >-
**Preview endpoint: integration testing only.** Access is granted under
a written testing agreement and is enabled per API key. Request text is
sent to the model provider and recorded in Vera's tracing system, and
the endpoint carries no availability or stability commitment. Call it
server to server: no CORS headers are sent, so a browser cannot read a
cross-origin response, and your API key must never reach a browser.
Runs Vera's agentic engine and streams the answer along with the tool
activity that produced it. The `tools` parameter selects which optional
tools the agent may call, so a single integration can offer a different
capability set at each step of a workflow. Omitting it is the same as
sending an empty array: there is no per-key default set.
Literature retrieval is always on and is not part of `tools`, so a
caller cannot disable the search every answer depends on. A request
without `thread_id` starts a new thread, saved under your partner
account, and its id comes back in the `x-thread-id` header. Send that id
as `thread_id` to ask a follow-up: Vera answers the new question with
the earlier turns of that thread in context, and saves it to the same
thread. If a streamed connection drops, reconnect with [GET
/api/chat/v3/threads/{threadId}/stream](/api-reference/v3/reconnect-to-an-agentic-stream),
using the same id.
See the [tool guide](/docs/guides/agentic-tools) for the tool groups and
the [agentic streaming guide](/docs/guides/agentic-streaming) for the
event format, which is **not** the same as `/api/chat/v2`.
operationId: chatV3
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentChatRequest'
responses:
'200':
description: >-
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](/docs/guides/agentic-streaming).
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.
content:
text/event-stream:
schema:
type: string
example: >+
data: {"type":"start"}
data:
{"type":"tool-input-available","toolCallId":"medcalc-1","toolName":"medcalc","input":{}}
data:
{"type":"tool-output-available","toolCallId":"medcalc-1","output":{"calcId":"chad","title":"CHA2DS2-VASc
Score"}}
data:
{"type":"data-sources","id":"sources-1","data":{"sources":[{"sourceId":5,"kind":"paper","title":"Community-Acquired
Pneumonia Treatment Guidelines","firstAuthor":"Metlay
JP","year":"2019","doi":"10.1001/jama.2023.0001","isGuideline":true,"evidenceStrength":"High"}]}}
data: {"type":"text-delta","id":"text-1","delta":"Amoxicillin 1
g"}
data: {"type":"finish"}
data: [DONE]
application/json:
schema:
$ref: '#/components/schemas/AgentChatResponse'
example:
thread_id: 7d1f0c52-3a9e-4b8e-9f6a-2c4d5e6f7a81
message_id: c3b2a190-8f7e-4d6c-b5a4-938271605f4e
answer: >-
Amoxicillin 1 g orally three times daily is the usual adult
dose for outpatient community-acquired
pneumonia.
references:
- sourceId: 5
kind: paper
title: Community-Acquired Pneumonia Treatment Guidelines
firstAuthor: Metlay JP
year: '2019'
doi: 10.1001/jama.2023.0001
isGuideline: true
evidenceStrength: High
tool_outputs:
- tool: medcalc
output:
calcId: chad
title: CHA2DS2-VASc Score
headers:
x-thread-id:
description: >-
UUID of the thread this answer is saved in. Use it to reconnect
a dropped stream.
schema:
type: string
format: uuid
x-vera-request-id:
description: Correlation id for this request. Quote it in support requests.
schema:
type: string
'400':
description: >-
The body failed validation, or `tools` contains an id outside the
documented vocabulary. The always-on tool names (`retrieve`, `stop`)
are not part of the vocabulary and are rejected here too, as is any
unknown field: the body is validated strictly.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
example:
error: The payload is not valid
message: The payload is not valid
code: VALIDATION_ERROR
'401':
description: Missing or invalid API key.
content:
text/plain:
schema:
type: string
example: Unauthorized
'403':
description: >-
Either this key is not enabled for the agentic endpoint, or it is
not provisioned for a requested tool. Both are granted under the
testing agreement: contact support@verahealth.ai.
content:
application/json:
schema:
$ref: '#/components/schemas/AgentChatError'
examples:
access_not_enabled:
summary: Key not enabled for this endpoint
value:
error:
code: access_not_enabled
message: >-
This API key is not enabled for the agentic endpoint.
Contact support@verahealth.ai.
tool_not_enabled:
summary: Tool group not provisioned for this key
value:
error:
code: tool_not_enabled
message: tool "medcalc" is not enabled for this API key
'404':
description: >-
`thread_id` names no thread, or a thread that belongs to another
partner.
content:
application/json:
schema:
$ref: '#/components/schemas/AgentChatError'
examples:
thread_not_found:
summary: Unknown thread
value:
error:
code: thread_not_found
message: No thread with this id.
'409':
description: >-
An answer is still being generated in the thread named by
`thread_id`. Wait for it to finish (or reconnect to it), then send
the follow-up again.
content:
application/json:
schema:
$ref: '#/components/schemas/AgentChatError'
examples:
answer_in_progress:
summary: Answer in progress
value:
error:
code: answer_in_progress
message: >-
An answer is still being generated in this thread. Wait
for it to finish, then send the follow-up.
'413':
description: >-
`question_too_long`: the new question alone exceeds the inline
length limit. `conversation_too_long`: the thread named by
`thread_id` has reached its maximum length, so start a new thread
without `thread_id` to continue.
content:
application/json:
schema:
$ref: '#/components/schemas/AgentChatError'
examples:
question_too_long:
summary: Question too long
value:
error:
code: question_too_long
message: >-
The request exceeds the maximum supported context
length.
conversation_too_long:
summary: Conversation too long
value:
error:
code: conversation_too_long
message: >-
This conversation has reached its maximum length. Start
a new thread to continue.
'422':
description: >-
The request was refused on content-policy grounds (`stream: false`
only).
content:
application/json:
schema:
$ref: '#/components/schemas/AgentChatError'
examples:
content_policy_stop:
summary: Content policy
value:
error:
code: content_policy_stop
message: >-
This request violates our Terms of Service. Please try
again if you believe this is an error.
'429':
description: >-
Rate limit exceeded. Retry after the interval in the `Retry-After`
header.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
'500':
description: Unexpected server error.
content:
application/json:
schema:
$ref: '#/components/schemas/AgentChatError'
examples:
internal_error:
summary: Internal error
value:
error:
code: internal_error
message: Internal server error
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl -N -X POST https://www.verahealth.ai/api/chat/v3 \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "What is the usual adult oral dose of amoxicillin for pneumonia?",
"tools": ["drug"]
}'
- lang: javascript
label: JavaScript
source: >-
const response = await
fetch("https://www.verahealth.ai/api/chat/v3", {
method: "POST",
headers: {"x-api-key": process.env.VERA_API_KEY, "Content-Type": "application/json"},
body: JSON.stringify({
question: "What is the usual adult oral dose of amoxicillin for pneumonia?",
tools: ["drug"],
stream: false,
}),
});
const {answer, references} = await response.json();
console.log(answer, references.map((reference) => reference.title));
- lang: python
label: Python
source: |-
import os, requests
response = requests.post(
"https://www.verahealth.ai/api/chat/v3",
headers={"x-api-key": os.environ["VERA_API_KEY"]},
json={
"question": "What is the usual adult oral dose of amoxicillin for pneumonia?",
"tools": ["drug"],
"stream": False,
},
timeout=300,
)
body = response.json()
print(body["answer"])
print([reference["title"] for reference in body["references"]])
components:
schemas:
AgentChatRequest:
type: object
required:
- question
description: Request envelope for `POST /api/chat/v3`.
properties:
question:
type: string
minLength: 1
description: The clinical question to answer.
example: What is the usual adult oral dose of amoxicillin for pneumonia?
thread_id:
type: string
format: uuid
description: >-
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:
type: array
items:
$ref: '#/components/schemas/AgentToolId'
description: >-
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.
example:
- drug
- medcalc
country:
type: string
enum:
- FR
- IT
description: >-
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.
example: FR
stream:
type: boolean
default: true
description: >-
`true` (default) streams the AI SDK UI message stream. `false`
returns a single JSON payload.
suggestions:
type: boolean
default: false
description: >-
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.
AgentChatResponse:
type: object
description: 'Non-streaming response (`stream: false`).'
properties:
thread_id:
type: string
format: uuid
description: >-
The thread this answer is saved in. Same value as the `x-thread-id`
header.
message_id:
type: string
format: uuid
description: >-
The id the answer is saved under. A refused request never reaches
this body: it returns `422 content_policy_stop`.
answer:
type: string
description: >-
The answer in Markdown, carrying the same citation markup the stream
does: a `claim` tag names the `sourceId` of
the reference behind the claim (the number before the dash). Empty
when the agent's deliverable is a tool payload: see `tool_outputs`.
references:
type: array
items:
$ref: '#/components/schemas/AgentReference'
tool_outputs:
type: array
items:
$ref: '#/components/schemas/AgentToolOutput'
suggestions:
$ref: '#/components/schemas/AgentSuggestedQuestions'
description: 'Present only when the request set `suggestions: true`.'
ValidationError:
type: object
description: >-
Request-validation failure. Emitted by the shared API layer before the
route runs, so it does not use the ChatError envelope and carries no
`metadata` echo. The message is deliberately generic and does not name
the offending field.
required:
- error
- message
- code
properties:
error:
type: string
example: The payload is not valid
message:
type: string
example: The payload is not valid
code:
type: string
enum:
- VALIDATION_ERROR
AgentChatError:
type: object
required:
- error
description: Error envelope.
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- access_not_enabled
- tool_not_enabled
- question_too_long
- content_policy_stop
- internal_error
- thread_not_found
- answer_in_progress
- conversation_too_long
message:
type: string
RateLimitError:
type: object
required:
- error
description: >-
Rate-limit error body. Emitted by the auth layer, so it carries no
`metadata` echo (unlike the ChatError envelope).
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- rate_limited
message:
type: string
AgentToolId:
type: string
description: >-
A tool you can switch on or off per request. Literature retrieval is
always on and is not listed here: it cannot be disabled.
enum:
- drug
- medcalc
- patientHandout
- priorAuth
x-enum-descriptions:
drug: 'Drug monograph lookup: dosing, interactions, and labelling.'
medcalc: 'Clinical calculators: resolves and computes a score from the question.'
patientHandout: >-
Patient-facing care instructions. Delivered as tool input; the answer
text stays empty.
priorAuth: >-
Prior-authorization letter. Delivered as tool input; the answer text
stays empty.
AgentReference:
type: object
properties:
sourceId:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
The number before the dash in a `cite index`, and the whole index of
a `figure` or `calculator` placement.
example: 5
kind:
type: string
enum:
- paper
- drug
- figure
- calculator
description: >-
What the source is. `paper` covers journal articles and guidelines;
`drug` a monograph; `figure` an image the answer places;
`calculator` a computed score.
title:
type: string
description: >-
Paper or guideline title, drug name, figure caption, or calculator
name.
example: Community-Acquired Pneumonia Treatment Guidelines
firstAuthor:
type: string
description: Papers only.
example: Metlay JP
journal:
type: string
description: Papers only.
year:
type: string
description: Papers only.
example: '2019'
doi:
type: string
description: Papers only. Absent when the paper has none.
example: 10.1001/jama.2023.0001
imageUrl:
type: string
description: >-
Figures only: the image a `figure` placement renders. Fetch it while
rendering the answer rather than storing the link: the URL is not
part of this contract and may change or stop resolving at any time.
isGuideline:
type: boolean
description: >-
Papers only: whether the source is a clinical guideline rather than
a primary study. Absent on drug, figure and calculator sources.
evidenceStrength:
type: string
enum:
- Very High
- High
- Moderate
- Low
description: Graded level of evidence for the paper. Absent when it has none.
required:
- sourceId
- kind
description: >-
A source the answer drew on. Every reference is citable: `sourceId` is
the number a `cite`, `figure` or `calculator` index in the answer
resolves to.
AgentToolOutput:
type: object
required:
- tool
- output
description: >-
One reported tool call. Only the tools below report a payload;
retrieval, the drug lookup and the bibliographic lookups do their work
on the model channel and reach you as references and answer text. Each
payload is trimmed to its documented fields at every depth before it
leaves the server.
properties:
tool:
type: string
enum:
- medcalc
- patientHandout
- priorAuth
example: medcalc
output:
oneOf:
- $ref: '#/components/schemas/AgentToolPayloadMedcalc'
- $ref: '#/components/schemas/AgentToolPayloadPatientHandout'
- $ref: '#/components/schemas/AgentToolPayloadPriorAuth'
AgentSuggestedQuestions:
type: object
description: Three follow-up questions derived from the question and the answer.
properties:
question_1:
type: string
question_2:
type: string
question_3:
type: string
required:
- question_1
- question_2
- question_3
AgentToolPayloadMedcalc:
type: object
properties:
calcId:
anyOf:
- type: string
- type: 'null'
title:
anyOf:
- type: string
- type: 'null'
inputs:
type: array
items:
type: object
properties:
label:
type: string
value:
type: string
required:
- label
- value
sourceId:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
required:
- calcId
- title
description: >-
The `medcalc` tool's payload: which calculator ran, the inputs it
resolved from the question, and the `sourceId` a `calculator` placement
in the answer resolves to.
AgentToolPayloadPatientHandout:
type: object
properties:
title:
type: string
content:
type: string
language:
type: string
required:
- title
- content
description: >-
The `patientHandout` tool's deliverable: the document the model
authored, in Markdown. On these turns `answer` is empty.
AgentToolPayloadPriorAuth:
type: object
properties:
title:
type: string
content:
type: string
required:
- title
- content
description: >-
The `priorAuth` tool's deliverable: the letter the model authored, in
Markdown. On these turns `answer` is empty.
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
API key for authentication. Contact support@verahealth.ai to obtain your
API key.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.