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

# Streaming events

> Reference for every event type in the Chat API's SSE response stream.

The Chat API returns a Server-Sent Events (SSE) stream. Each frame is a single JSON object preceded by `data: ` and terminated by a blank line:

```
data: {JSON_OBJECT}

```

Every event is a flat JSON object with a `type` discriminator.

The endpoint also supports `stream: false`, which returns a single JSON payload instead of a stream — see [`POST /api/chat/v2`](https://docs.verahealth.ai/api-reference/v2/send-a-chat-message) for that shape.

## Response headers

| Header | Description |
| - | - |
| `x-thread-id` | UUID of the thread created for this call. |
| `x-message-id` | UUID of the message being generated. |
| `x-workflow-run-id` | Run id for `GET /api/chat/v2/stream/{runId}` reconnect. |

## Event catalog

### `thread-info`

First event. Confirms the server-side thread and message IDs.

```json theme={null}
{"type": "thread-info", "threadId": "550e8400-...", "messageId": "660f9500-..."}
```

### `workflow-run-id`

Emitted once the run starts. Save `workflowRunId` to [reconnect](https://docs.verahealth.ai/docs/guides/reconnecting-a-stream.md) if your connection drops.

```json theme={null}
{"type": "workflow-run-id", "workflowRunId": "wf_01H9Y..."}
```

### `text-start`

Marks the start of answer text.

```json theme={null}
{"type": "text-start", "id": "uuid"}
```

### `text-delta`

A chunk of the answer. Append `delta` to build the full answer (markdown).

```json theme={null}
{"type": "text-delta", "id": "uuid", "delta": "Amoxicillin is the recommended"}
```

### `text-end`

Marks the end of answer text.

```json theme={null}
{"type": "text-end", "id": "uuid"}
```

### `data-references`

Literature references cited in the answer.

```json theme={null}
{
  "type": "data-references",
  "data": [
    {
      "paperId": "517a102c-ca7a-4db2-8184-293656b3589e",
      "title": "Community-Acquired Pneumonia Treatment Guidelines",
      "journal": "JAMA",
      "firstAuthor": "Smith J",
      "year": 2023,
      "doi": "10.1001/jama.2023.12345",
      "pmid": "37654321",
      "studyTypes": ["guideline"],
      "evidenceTier": 0,
      "isGuideline": true,
      "journalTier": "top",
      "citationCount": 150,
      "citationTrend": "stable",
      "isLandmark": false,
      "isOpenAccess": true
    }
  ]
}
```

### `data-doi-reference-map`

Maps inline citation numbers (`[1]`, `[2]`) in the answer to DOI/PMID identifiers. May arrive multiple times during streaming. Complete when `isFinal: true`.

```json theme={null}
{
  "type": "data-doi-reference-map",
  "data": {
    "referenceMap": {"1": "10.1001/jama.2023.12345", "2": "pmid:37654321"},
    "totalReferences": 2,
    "isFinal": true
  }
}
```

### `data-stop`

Vera declined the request. No answer text follows, but `finish` still arrives with `status: "complete"` — a refusal is not a stream failure.

Branch on `code`. `message` is an English explanation, safe to display as-is.

| `code` | Meaning |
| - | - |
| `content_policy_stop` | The request was blocked by our content policy. |
| `question_too_long` | `question` exceeds 200,000 characters. |

```json theme={null}
{
  "type": "data-stop",
  "data": {
    "code": "content_policy_stop",
    "message": "This request violates our Terms of Service. Please try again if you believe this is an error."
  }
}
```

On the non-streaming path (`stream: false`) the same codes arrive as an error envelope: `content_policy_stop` as `422`, `question_too_long` as `413`.

### `finish`

Stream complete. Close the connection after this event.

```json theme={null}
{
  "type": "finish",
  "status": "complete",
  "messageId": "660f9500-...",
  "saved": true,
  "referencesCount": 12
}
```

## Reference shape

Each entry in a `data-references` event:

```typescript theme={null}
{
  paperId: string | null;       // Stable opaque identifier — falls back to DOI or PMID. Treat as opaque.
  pmid: string | null;
  doi: string | null;

  title: string;
  journal: string | null;
  firstAuthor: string | null;
  year: number | null;

  studyTypes: string[];         // e.g. ["meta_analysis", "systematic_review"]
  evidenceTier: number | null;  // 0=guideline, 1=MA/SR, 2=RCT, 3=cohort, 4=case, 5=editorial
  isGuideline: boolean;

  journalTier: string | null;   // "top", "high", "good", "standard"
  citationCount: number | null;
  citationTrend: string | null; // "accelerating", "stable", "declining"
  isLandmark: boolean;          // top 1% citation percentile
  isOpenAccess: boolean;
}
```


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