> ## 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. # Chat > Send a medical question and receive an answer as a Server-Sent Events (SSE) stream. The stream contains answer text, DOI/PMID citation mappings, reference metadata, and suggested follow-up questions. New integrations should use [POST /api/chat/v2](/api-reference/v2/send-a-chat-message). ## OpenAPI ````yaml /docs/api-reference/openapi.json post /api/chat/v1 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/v1: post: tags: - v1 summary: Chat description: >- Send a medical question and receive an answer as a Server-Sent Events (SSE) stream. The stream contains answer text, DOI/PMID citation mappings, reference metadata, and suggested follow-up questions. New integrations should use [POST /api/chat/v2](/api-reference/v2/send-a-chat-message). operationId: chatV1 requestBody: required: true content: application/json: schema: type: object required: - prompt properties: traceId: type: string description: >- Optional unique identifier for request tracing. Auto-generated if not provided. example: 550e8400-e29b-41d4-a716-446655440000 prompt: type: string description: The medical question to answer. example: >- What is the first-line treatment for hypertension in a 55-year-old male with diabetes? examples: simple_question: summary: Simple medical question (no traceId) value: prompt: What is the first-line treatment for hypertension? clinical_question: summary: Clinical decision support (with custom traceId) value: prompt: >- What are the latest guidelines for managing type 2 diabetes in patients with chronic kidney disease? traceId: 550e8400-e29b-41d4-a716-446655440001 drug_information: summary: Drug information query value: prompt: >- What are the contraindications and interactions for metformin? traceId: 550e8400-e29b-41d4-a716-446655440002 responses: '200': description: >- Server-Sent Events stream (`Content-Type: text/event-stream`). Each frame is `data: {JSON_OBJECT}` and every event has `type` and `content` fields. The stream terminates with `data: [DONE]`. ## Event types | `content.nodeName` | Description | |--------------------|-------------| | `STREAM` | Chunks of answer text. | | `DOI_REFERENCE_MAP` | Maps inline reference numbers to DOI/PMID links. | | `REFERENCES` | Reference metadata (title, journal, authors, DOI, PMID, year). | | `SUGGEST` | Up to 3 suggested follow-up questions (emitted in a `NodeEnd` wrapper at the end of the stream). | ### Example events ```json {"type": "NodeChunk", "content": {"nodeName": "STREAM", "content": "The first-line treatment..."}} {"type": "NodeChunk", "content": {"nodeName": "DOI_REFERENCE_MAP", "content": {"referenceMap": {"1": "https://doi.org/10.1056/NEJMoa2035389"}, "totalReferences": 1}}} {"type": "NodeChunk", "content": {"nodeName": "REFERENCES", "content": [{"title": "Hypertension Guidelines 2023", "metadata": {"title": "2023 ACC/AHA Guidelines", "journal": "JACC", "pmid": "12345678", "doi": "10.1056/NEJMoa2035389", "year": 2023}}]}} {"type": "NodeEnd", "content": {"message": {"nodeName": "SUGGEST", "value": {"question_1": "...", "question_2": "...", "question_3": "..."}}}} ``` content: text/event-stream: schema: type: string description: >- Server-Sent Events stream containing JSON objects. Each event has a `type` and `content` field. See the endpoint description for detailed event type documentation. examples: stream_event: summary: Answer text chunk value: >+ data: {"type":"NodeChunk","content":{"nodeName":"STREAM","content":"The first-line treatment for hypertension typically includes..."}} reference_event: summary: Citation references value: >+ data: {"type":"NodeChunk","content":{"nodeName":"DOI_REFERENCE_MAP","content":{"referenceMap":{"1":"https://doi.org/10.1056/NEJMoa2035389"},"totalReferences":1,"isFinal":false}}} completion: summary: Stream completion value: |+ data: [DONE] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' deprecated: true security: - apiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST https://www.verahealth.ai/api/chat/v1 \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "What is the first-line treatment for hypertension?" }' - lang: javascript label: JavaScript source: >- const response = await fetch('https://www.verahealth.ai/api/chat/v1', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'What is the first-line treatment for hypertension?', traceId: '550e8400-e29b-41d4-a716-446655440000' // Optional: for internal tracking }) }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); const lines = chunk.split('\\n\\n'); for (const line of lines) { if (line.startsWith('data: ')) { const data = line.slice(6); if (data === '[DONE]') break; const event = JSON.parse(data); console.log('Event:', event); } } } - lang: python label: Python source: >- import requests import json url = 'https://www.verahealth.ai/api/chat/v1' headers = { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'prompt': 'What is the first-line treatment for hypertension?', 'traceId': '550e8400-e29b-41d4-a716-446655440000' # Optional: for internal tracking } with requests.post(url, headers=headers, json=data, stream=True) as response: for line in response.iter_lines(): if line: line = line.decode('utf-8') if line.startswith('data: '): data = line[6:] if data == '[DONE]': break event = json.loads(data) print('Event:', event) components: responses: BadRequest: description: Bad request - Invalid parameters or missing required fields content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid request body message: Either messageId or prompt is required 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 NotFound: description: Not found - Message ID does not exist content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Message not found message: The specified messageId does not exist 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 schemas: Error: type: object properties: error: type: string description: Error message message: type: string description: Detailed error message details: type: string description: Additional error details 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 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.