> ## 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.

# Quickstart

> Make your first call to the Vera Health Chat API in under 5 minutes.

## 1. Get an API key

Contact [support@verahealth.ai](mailto:support@verahealth.ai) to request credentials.

> [!WARNING]
>
> Keep your API key secret. Treat it like a password and never commit it to source control.

## 2. Send your first request

Send a `POST` request to `/api/chat/v2` with your API key in the `x-api-key` header and a clinical question in the body. By default the response is a Server-Sent Events stream; set `stream: false` to receive a single JSON payload instead.

```bash theme={null}
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"
    }
  }'
```

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `question` | string | yes | The clinical question to answer. |
| `context` | string \| array | no | Prior conversation. Free-form string or array of `{role, content}` turns. |
| `metadata` | object | yes | Your identifiers and routing fields. Returned unchanged on the non-streaming response. |
| `stream` | boolean | no | `true` (default) for an SSE stream, `false` for a single JSON payload. |

### `metadata` fields

| Field | Required | Description |
| - | - | - |
| `source` | yes | Your integration identifier (e.g. your product name). |
| `thread_id` | yes | Your thread identifier. |
| `message_id` | yes | Your message identifier. |
| `user_id` | yes | Your end-user identifier. |
| `timestamp` | yes | ISO 8601 timestamp. |
| `variation` | no | Free-form experiment / prompt-variation tag. |

Any additional fields you include in `metadata` are returned unchanged on the non-streaming response — useful for your own correlation ids.

## 3. Parse the SSE stream

The response is a Server-Sent Events stream. Each frame is a single line:

```
data: {JSON_OBJECT}

```

Every event is a flat JSON object with a `type` field. The events you'll care about most are:

| Event | What it carries |
| - | - |
| `thread-info` | The `threadId` and `messageId` for this request. |
| `workflow-run-id` | A `workflowRunId` — save it to [resume the stream](https://docs.verahealth.ai/docs/guides/reconnecting-a-stream.md) if your connection drops. |
| `text-delta` | A chunk of answer text. Concatenate `delta` values to build the answer. |
| `data-references` | The list of cited papers with metadata (title, journal, DOI, PMID, ...). |
| `data-doi-reference-map` | Maps inline `[1]`, `[2]` markers in the answer to DOIs/PMIDs. |
| `finish` | Stream is complete — close the connection. |

See the [streaming guide](https://docs.verahealth.ai/docs/guides/streaming.md) for the full event catalog.

## 4. JavaScript example

```javascript theme={null}
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}`);

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
let answer = "";

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 "text-delta":
        answer += event.delta;
        break;
      case "data-references":
        console.log("References:", event.data);
        break;
      case "finish":
        console.log("Done.");
        break;
    }
  }
}

console.log(answer);
```

## 5. Python example

```python theme={null}
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(),
    },
}

answer = ""
with requests.post(url, headers=headers, json=payload, stream=True) as r:
    r.raise_for_status()
    for raw in r.iter_lines(decode_unicode=True):
        if not raw or not raw.startswith("data: "):
            continue
        event = json.loads(raw[6:])
        if event["type"] == "text-delta":
            answer += event["delta"]
        elif event["type"] == "finish":
            break

print(answer)
```

## Next steps

> [card] [Streaming events](https://docs.verahealth.ai/docs/guides/streaming.md)
>
> Full reference for every event type in the stream.

> [card] [Reconnecting a stream](https://docs.verahealth.ai/docs/guides/reconnecting-a-stream.md)
>
> Resume a stream after a disconnect using the workflow run ID.

> [card] [API reference](https://docs.verahealth.ai/api-reference/v2/send-a-chat-message.md)
>
> Endpoint schemas, request/response examples, and playgrounds.

> [card] [Support](mailto:support@verahealth.ai)
>
> Email us for help integrating.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.