Quickstart

1. Get an API key

Contact support@verahealth.ai to request credentials.

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.

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 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 for the full event catalog.

4. JavaScript example

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

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

Streaming events

Full reference for every event type in the stream.

Reconnecting a stream

Resume a stream after a disconnect using the workflow run ID.

API reference

Endpoint schemas, request/response examples, and playgrounds.

Support

Email us for help integrating.

Get Started

Chat API

Agentic API (preview)

1. Get an API key

2. Send your first request

Request body

`metadata` fields

3. Parse the SSE stream

4. JavaScript example

5. Python example

Next steps

Streaming events

Reconnecting a stream

API reference

Support

​1. Get an API key

​2. Send your first request

​Request body

​metadata fields

​3. Parse the SSE stream

​4. JavaScript example

​5. Python example

​Next steps

Streaming events

Reconnecting a stream

API reference

Support

1. Get an API key

2. Send your first request

Request body

`metadata` fields

3. Parse the SSE stream

4. JavaScript example

5. Python example

Next steps