> ## 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. # Send a chat message > Send a clinical question and receive an AI-generated answer. By default the response is a Server-Sent Events stream of flat JSON events with a `type` discriminator (`text-delta`, `data-references`, `finish`, …). See the [streaming guide](/docs/guides/streaming) for the full event catalog. Set `stream: false` to receive a single JSON payload instead — the non-streaming response groups Vera-specific fields under `vendor_metadata` and echoes your request `metadata` unchanged. Save the `workflow-run-id` event's `workflowRunId` (streaming) or `vendor_metadata.workflow_run_id` (non-streaming) — you can use either to resume the stream via [GET /api/chat/v2/stream/{runId}](/api-reference/v2/resume-a-chat-stream) if your connection drops. Each cited reference includes: `paperId`, `pmid`, `doi`, `title`, `journal`, `firstAuthor`, `year`, `studyTypes`, `evidenceTier`, `isGuideline`, `journalTier`, `citationCount`, `citationTrend`, `isLandmark`, and `isOpenAccess`. ## OpenAPI ````yaml /docs/api-reference/openapi.json post /api/chat/v2 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/v2: post: tags: - v2 summary: Send a chat message description: >- Send a clinical question and receive an AI-generated answer. By default the response is a Server-Sent Events stream of flat JSON events with a `type` discriminator (`text-delta`, `data-references`, `finish`, …). See the [streaming guide](/docs/guides/streaming) for the full event catalog. Set `stream: false` to receive a single JSON payload instead — the non-streaming response groups Vera-specific fields under `vendor_metadata` and echoes your request `metadata` unchanged. Save the `workflow-run-id` event's `workflowRunId` (streaming) or `vendor_metadata.workflow_run_id` (non-streaming) — you can use either to resume the stream via [GET /api/chat/v2/stream/{runId}](/api-reference/v2/resume-a-chat-stream) if your connection drops. Each cited reference includes: `paperId`, `pmid`, `doi`, `title`, `journal`, `firstAuthor`, `year`, `studyTypes`, `evidenceTier`, `isGuideline`, `journalTier`, `citationCount`, `citationTrend`, `isLandmark`, and `isOpenAccess`. operationId: chatV2 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatRequest' examples: simple_question: summary: Simple medical question (streaming, default) value: question: What is the first-line treatment for hypertension? metadata: source: your-integration thread_id: thr_demo message_id: msg_001 user_id: user_demo timestamp: '2026-06-01T12:00:00Z' non_streaming: summary: 'Single JSON payload (`stream: false`)' value: question: Is amoxicillin safe with warfarin? metadata: source: your-integration thread_id: thr_abc message_id: msg_002 user_id: user_123 timestamp: '2026-06-01T12:00:00Z' stream: false with_context: summary: With prior conversation as structured turns value: question: What about other penicillins? context: - role: user content: Is amoxicillin safe with warfarin? - role: assistant content: Amoxicillin can interact with warfarin... metadata: source: your-integration thread_id: thr_abc message_id: msg_003 user_id: user_123 timestamp: '2026-06-01T12:01:00Z' responses: '200': description: >- When `stream` is `true` (default), the response is a Server-Sent Events stream (`Content-Type: text/event-stream`). Each frame is `data: {JSON}\n\n` and carries a top-level `type` discriminator. See the [streaming guide](/docs/guides/streaming) for the full event catalog. When `stream` is `false`, the response is a single JSON payload (`Content-Type: application/json`) returned once the answer is fully generated. It carries your request `metadata` echoed byte-identical, and groups Vera-specific fields (`references`, `progress`, `workflow_run_id`, `doi_reference_map`, `evidence_levels`, `suggested_questions`) under `vendor_metadata`. See the `application/json` example below. ## Streaming event types | Event | Description | |-------|-------------| | `thread-info` | First event. Carries `threadId` and `messageId`. | | `workflow-run-id` | Carries `workflowRunId` — save it to resume the stream. | | `text-start` / `text-delta` / `text-end` | Answer text. Concatenate each `delta` to build the full markdown answer. | | `data-references` | Cited papers with metadata. | | `data-evidence-levels` | Map of `paper_id` / `doi` / `pmid` → `EvidenceLevel` (study type, Oxford level, strength assessment) for cited references. Emitted as evidence becomes available; may be emitted multiple times during a stream. See the `EvidenceLevel` schema. | | `data-doi-reference-map` | Maps inline `[1]`, `[2]` markers to DOI/PMID URLs. Last emission has `isFinal: true`. | | `data-stop` | Vera declined the request. Branch on `data.code`: `content_policy_stop` or `question_too_long`. No answer text follows, but `finish` still arrives with `status: "complete"`. | | `finish` | Terminal event. Close the connection after this. | ## Response headers (streaming only) | Header | Description | |--------|-------------| | `x-thread-id` | UUID of the thread created for this request. | | `x-message-id` | UUID of the message being generated. | | `x-workflow-run-id` | Run id — use it to resume via `GET /api/chat/v2/stream/{runId}`. | headers: x-thread-id: description: UUID of the newly created thread (streaming responses only). schema: type: string format: uuid x-message-id: description: UUID of the message being generated (streaming responses only). schema: type: string format: uuid x-workflow-run-id: description: >- Run id for `GET /api/chat/v2/stream/{runId}` reconnect (streaming responses only). schema: type: string content: text/event-stream: schema: type: string description: >- SSE stream of flat JSON events. Each event has a `type` discriminator. See the streaming guide for the full event catalog. examples: thread_info: summary: First event — thread IDs value: >+ data: {"type":"thread-info","threadId":"550e8400-e29b-41d4-a716-446655440000","messageId":"660f9500-e29b-41d4-a716-446655440001"} workflow_run_id: summary: Workflow run id (save for reconnection) value: >+ data: {"type":"workflow-run-id","workflowRunId":"wf_01H9YABC..."} text_delta: summary: Answer text chunk value: >+ data: {"type":"text-delta","id":"uuid","delta":"The first-line treatment for hypertension typically includes...","sequence":1} finish: summary: Terminal finish event value: >+ data: {"type":"finish","status":"complete","messageId":"660f9500-...","saved":true,"referencesCount":35} application/json: schema: $ref: '#/components/schemas/ChatResponse' examples: non_streaming: summary: 'Single JSON payload (`stream: false`)' value: answer: >- Amoxicillin can interact with warfarin by displacing it from plasma proteins and altering gut flora that produce vitamin K... metadata: source: your-integration thread_id: thr_abc message_id: msg_002 user_id: user_123 timestamp: '2026-06-01T12:00:00Z' vendor_metadata: type: vendor_metadata workflow_run_id: run_123 thread_id: 550e8400-e29b-41d4-a716-446655440000 message_id: 660f9500-e29b-41d4-a716-446655440001 references: - paperId: 517a102c-ca7a-4db2-8184-293656b3589e pmid: '37654321' doi: 10.1378/chest.11-2295 title: ACCP Guidelines on Antithrombotic Therapy journal: Chest firstAuthor: Smith J year: 2012 studyTypes: - guideline evidenceTier: 0 isGuideline: true journalTier: top citationCount: 482 citationTrend: stable isLandmark: true isOpenAccess: true doi_reference_map: referenceMap: '1': https://doi.org/10.1378/chest.11-2295 totalReferences: 1 isFinal: true '400': description: >- Bad request — the body is not valid JSON or failed validation. `metadata` is echoed when present in the request. content: application/json: schema: $ref: '#/components/schemas/ChatError' examples: invalid_body: summary: Validation failed value: error: code: invalid_request_body message: metadata.thread_id is required metadata: source: your-integration thread_id: '' message_id: msg_002 user_id: user_123 timestamp: '2026-06-01T12:00:00Z' '401': $ref: '#/components/responses/Unauthorized' '413': description: >- `question` exceeds 200,000 characters. Shorten it and retry; retrying unchanged will fail again. Non-streaming only — the streaming path reports this as a `data-stop` event with `code: "question_too_long"`. content: application/json: schema: $ref: '#/components/schemas/ChatError' example: error: code: question_too_long message: Your query is 12,431 characters too long. metadata: source: your-integration thread_id: thr_abc message_id: msg_002 user_id: user_123 timestamp: '2026-06-01T12:00:00Z' '422': description: >- The request was blocked by our content policy. Retrying unchanged will fail again. Non-streaming only — the streaming path reports this as a `data-stop` event with `code: "content_policy_stop"`. content: application/json: schema: $ref: '#/components/schemas/ChatError' example: error: code: content_policy_stop message: >- This request violates our Terms of Service. Please try again if you believe this is an error. metadata: source: your-integration thread_id: thr_abc message_id: msg_002 user_id: user_123 timestamp: '2026-06-01T12:00:00Z' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' security: - apiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -N -X POST https://www.verahealth.ai/api/chat/v2 \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "question": "What is the first-line treatment for hypertension?", "metadata": { "source": "your-integration", "thread_id": "thr_demo", "message_id": "msg_001", "user_id": "user_demo", "timestamp": "2026-06-01T12:00:00Z" } }' - lang: javascript label: JavaScript source: >- const metadata = { source: 'your-integration', thread_id: 'thr_demo', message_id: 'msg_001', user_id: 'user_demo', timestamp: new Date().toISOString(), }; const response = await fetch('https://www.verahealth.ai/api/chat/v2', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ question: 'What is the first-line treatment for hypertension?', metadata, }), }); if (!response.ok) { throw new Error(`Request failed: ${response.status}`); } let workflowRunId = null; let answer = ''; const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = ''; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const frames = buffer.split('\n\n'); buffer = frames.pop() ?? ''; for (const frame of frames) { const line = frame.trim(); if (!line.startsWith('data: ')) continue; const event = JSON.parse(line.slice(6)); switch (event.type) { case 'workflow-run-id': workflowRunId = event.workflowRunId; // save for reconnection break; case 'text-delta': answer += event.delta; break; case 'data-references': console.log('References:', event.data); break; case 'data-stop': console.warn('Stopped:', event.data.message); break; case 'finish': console.log('Done.'); break; } } } console.log('Answer:', answer); - lang: python label: Python source: >- import json from datetime import datetime, timezone import requests url = 'https://www.verahealth.ai/api/chat/v2' headers = { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json', } payload = { 'question': 'What is the first-line treatment for hypertension?', 'metadata': { 'source': 'your-integration', 'thread_id': 'thr_demo', 'message_id': 'msg_001', 'user_id': 'user_demo', 'timestamp': datetime.now(timezone.utc).isoformat(), }, } with requests.post(url, headers=headers, json=payload, stream=True) as response: response.raise_for_status() workflow_run_id = None answer = '' for raw in response.iter_lines(decode_unicode=True): if not raw or not raw.startswith('data: '): continue event = json.loads(raw[6:]) etype = event.get('type') if etype == 'workflow-run-id': workflow_run_id = event['workflowRunId'] # save for reconnection elif etype == 'text-delta': answer += event['delta'] elif etype == 'data-stop': print('Stopped:', event['data']['message']) elif etype == 'finish': print('Done:', event) print('Answer:', answer) components: schemas: ChatRequest: type: object required: - question - metadata description: Request envelope for `POST /api/chat/v2`. properties: question: type: string description: The clinical question to answer. minLength: 1 example: Is amoxicillin safe with warfarin? context: description: >- Optional prior conversation. Accepts either a free-form string or an array of `{role, content}` turns (recommended). oneOf: - type: string - type: array items: $ref: '#/components/schemas/ConversationTurn' metadata: $ref: '#/components/schemas/ChatMetadata' stream: type: boolean description: >- If `true` (default), the response is an SSE stream. If `false`, the response is a single JSON payload returned once the answer is complete. default: true ChatResponse: type: object required: - answer - metadata - vendor_metadata description: Returned when `stream` is `false`. properties: answer: type: string description: The complete answer text (markdown). metadata: $ref: '#/components/schemas/ChatMetadata' vendor_metadata: $ref: '#/components/schemas/VendorMetadata' ChatError: type: object required: - error - metadata description: >- Error envelope. `metadata` is the request metadata echoed back when present (null otherwise). properties: error: type: object required: - code - message properties: code: type: string enum: - invalid_request_body - unauthorized - content_policy_stop - question_too_long - stream_failure - internal_error message: type: string metadata: oneOf: - $ref: '#/components/schemas/ChatMetadata' - type: 'null' ConversationTurn: type: object required: - role - content properties: role: type: string enum: - user - assistant content: type: string ChatMetadata: type: object required: - source - thread_id - message_id - user_id - timestamp description: >- Your identifiers and routing fields. Returned **byte-identical** on every response event. Additional fields are accepted and echoed unchanged. properties: type: type: string enum: - metadata source: type: string description: >- Your integration identifier. Echoed back unchanged on the non-streaming response. Pipeline routing is keyed off the API key, not this field — `metadata.source` cannot be used to select another partner's config. example: your-integration thread_id: type: string description: Your thread id. Vera does not interpret it. message_id: type: string description: Your message id. variation: type: string description: Free-form experiment / prompt variation tag. user_id: type: string description: Your end-user id (not a Vera user id). timestamp: type: string description: ISO 8601 timestamp. example: '2026-06-01T12:00:00Z' additionalProperties: true VendorMetadata: type: object description: Vera-owned provider data. Structure may evolve. properties: type: type: string enum: - vendor_metadata workflow_run_id: type: string description: Run id — used for `GET /api/chat/v2/stream/{runId}` reconnect. thread_id: type: string description: Vera-side thread UUID. message_id: type: string description: Vera-side message UUID. references: type: array items: type: object description: Cited papers with metadata. progress: type: object properties: steps: type: array items: type: object doi_reference_map: type: object description: Maps inline citation numbers in the answer to DOI/PMID URLs. evidence_levels: type: object description: >- Map keyed by `paper_id`, `doi`, and `pmid` (each cited reference appears under all the keys it carries) → `EvidenceLevel`. Populated from offline-graded `paper_loe` data with a legacy fallback for pre-Babylon refs. additionalProperties: $ref: '#/components/schemas/EvidenceLevel' usage: $ref: '#/components/schemas/TokenUsage' additionalProperties: true 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 Error: type: object properties: error: type: string description: Error message message: type: string description: Detailed error message details: type: string description: Additional error details EvidenceLevel: type: object description: >- Structured Level-of-Evidence assessment for a cited paper. Populated from the offline `paper_loe` table (Babylon refs) or the legacy `references.evidence_level` JSONB (pre-Babylon refs, mapped through the v1→v2 transformer). **Rollout note:** during the v1→v2 client rollout window the server also emits the deprecated v1 fields (`study_characteristics.design`, `study_characteristics.multicenter`, `study_characteristics.randomized`, top-level `strength_factors`) derived from the v2 fields so old clients keep rendering chips. New integrations should ignore the deprecated fields. required: - schema_version - summary - study_characteristics - quality_assessment - strength_tags - strength_notes - limitations - overall_strength properties: schema_version: type: integer enum: - 2 description: Wire-format version. Bumped when the shape changes. summary: type: string description: >- Long-form natural-language summary of the paper's methodology and evidence quality. study_characteristics: type: object required: - study_types - design_label - design_label_components - is_guideline - oxford_level - sample_size - follow_up_duration - population properties: study_types: type: array items: type: string enum: - rct - cohort - case_control - cross_sectional - case_report - diagnostic_accuracy - systematic_review - meta_analysis - guideline - narrative_review - editorial - preclinical description: >- Primary-first canonical study-type enums. May be empty when no enum fits — in that case `design_label` carries the description. design_label: type: string nullable: true description: >- Free-form design phrase. Set when `study_types=[]` or as a supplement to the enum array. design_label_components: type: array items: type: string description: >- Server-formatted display components for the design row: `study_types` mapped through the canonical English label map plus `design_label` appended (if set). Render directly — as chips, or joined with ' · ' for a single-line label. Clients should not duplicate this formatting. is_guideline: type: boolean description: >- Pre-computed: true when this paper should be rendered as a guideline (either `study_types` contains 'guideline' or `design_label` mentions it). Clients use this to hide Oxford-level chips since Oxford CEBM levels do not apply to guidelines. oxford_level: type: string enum: - 1a - 1b - 1c - 2a - 2b - 2c - 3a - 3b - '4' - '5' description: Oxford CEBM level. Not meaningful for guidelines. sample_size: type: integer nullable: true follow_up_duration: type: string nullable: true description: Free-form, e.g. '12 weeks', '3.2 years'. population: type: string nullable: true design: type: string nullable: true deprecated: true description: >- Deprecated. Use `study_types[0]` / `design_label`. Server-derived for v1 client back-compat during rollout. multicenter: type: boolean nullable: true deprecated: true description: >- Deprecated. Derived from `strength_tags.includes("multicenter")`. randomized: type: boolean nullable: true deprecated: true description: Deprecated. Derived from `study_types.includes("rct")`. quality_assessment: type: object required: - risk_of_bias - precision - confounding_adjustment properties: risk_of_bias: type: string enum: - Low - Moderate - High - Unknown precision: type: string enum: - High - Moderate - Low - Unknown confounding_adjustment: type: string enum: - Adjusted - Unadjusted - Not applicable - Unknown strength_tags: type: array items: type: string enum: - adjusted_analysis - blinded - duplicate_review - effect_size_ci - evidence_based_guideline - external_validation - formal_sr_methodology - large_sample - long_followup - matched_controls - multicenter - prospective - randomized - registered_protocol - rob_assessment - subgroup_sensitivity - validated_measures description: >- Canonical strength-tag enums. Render via the client-side label map (`formatStrengthTag`). strength_notes: type: array items: type: string description: >- Free-form notes that complement `strength_tags`. Rendered after the formatted tags in the snapshot view. strength_factors: type: array items: type: string deprecated: true description: >- Deprecated alias of `strength_tags`. Populated identically during the rollout window. limitations: type: array items: type: string overall_strength: type: string enum: - Very High - High - Moderate - Low TokenUsage: type: object description: >- Token counts for answer generation (input and output). Either may be null if the provider did not report it. Covers answer generation, not auxiliary retrieval/classification calls. properties: input_tokens: type: integer nullable: true output_tokens: type: integer nullable: true responses: Unauthorized: description: >- Unauthorized - missing or invalid x-api-key. Emitted by the auth layer before the route; the body is the plain-text string "Unauthorized" (not JSON, no metadata echo). content: text/plain: schema: type: string example: Unauthorized TooManyRequests: description: >- Rate limit exceeded for this API key. Retry after the Retry-After interval. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer RateLimit-Limit: description: Max requests allowed in the current window. schema: type: integer RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer RateLimit-Reset: description: Seconds until the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/RateLimitError' example: error: code: rate_limited message: >- Rate limit exceeded. Retry after the interval in the Retry-After header. InternalServerError: description: Internal server error - An unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Internal server error message: An unexpected error occurred while processing your request 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.