Streaming events

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

{"type": "thread-info", "threadId": "550e8400-...", "messageId": "660f9500-..."}

`workflow-run-id`

Emitted once the run starts. Save workflowRunId to reconnect if your connection drops.

{"type": "workflow-run-id", "workflowRunId": "wf_01H9Y..."}

`text-start`

Marks the start of answer text.

{"type": "text-start", "id": "uuid"}

`text-delta`

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

{"type": "text-delta", "id": "uuid", "delta": "Amoxicillin is the recommended"}

`text-end`

Marks the end of answer text.

{"type": "text-end", "id": "uuid"}

`data-references`

Literature references cited in the answer.

{
  "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.

{
  "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.

{
  "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.

{
  "type": "finish",
  "status": "complete",
  "messageId": "660f9500-...",
  "saved": true,
  "referencesCount": 12
}

Reference shape

Each entry in a data-references event:

{
  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;
}

Get Started

Chat API

Agentic API (preview)

Response headers

Event catalog

`thread-info`

`workflow-run-id`

`text-start`

`text-delta`

`text-end`

`data-references`

`data-doi-reference-map`

`data-stop`

`finish`

Reference shape

​Response headers

​Event catalog

​thread-info

​workflow-run-id

​text-start

​text-delta

​text-end

​data-references

​data-doi-reference-map

​data-stop

​finish

​Reference shape

Response headers

Event catalog

`thread-info`

`workflow-run-id`

`text-start`

`text-delta`

`text-end`

`data-references`

`data-doi-reference-map`

`data-stop`

`finish`

Reference shape