Chats SSE
Stream chat responses token-by-token using Server-Sent Events on the chats endpoint.
Overview
The /v1/chats endpoint supports unidirectional server-to-client Server-Sent Events (SSE) to stream the assistant's reply incrementally instead of waiting for the full response.
Enabling streaming
Include the Accept: text/event-stream header in your request.
POST /v1/chats
Accept: text/event-stream
Content-Type: application/json
Authorization: Bearer <token>
{
"conversation_id": "conv_e389786b611e",
"input": "I have a headache and feel nauseous"
}When streaming is enabled, the response has Content-Type: text/event-stream and delivers a sequence of SSE events instead of a single JSON object.
Event types
Each SSE event has the format:
event: <event_name>
data: <json_payload>| Event | When emitted | Data schema |
|---|---|---|
delta | One or more times during a message response | DeltaEvent |
done | Once, at the end of every response (message or diagnosis) | ChatResponse |
error | If an error occurs during streaming | ErrorResponse |
delta events are only emitted for message responses. When the assistant returns a diagnosis, only a single done event is sent with the full result.
Event schemas
delta
Carries a partial text chunk.
interface DeltaEvent {
id: string; // Response ID, same across all events in the stream
output: {
content: string; // Partial message text
};
}Example:
event: delta
data: {"id":"resp_6e5d051505a0","output":{"content":"Where is"}}
event: delta
data: {"id":"resp_6e5d051505a0","output":{"content":" your headache located?"}}done
Always the last event in the stream. The payload is the complete ChatResponse — identical to what you would receive without streaming.
For a message response:
event: done
data: {"id":"resp_6e5d051505a0","created_at":1774530618,"is_complete":false,"conversation_id":"conv_e389786b611e","output":{"type":"message","content":"Where is your headache located?","media":[]},"findings":[...]}For a diagnosis response (no delta events precede this):
event: done
data: {"id":"resp_6e5d051505a0","created_at":1774530618,"is_complete":true,"conversation_id":"conv_e389786b611e","output":{"type":"diagnosis","diseases":[...],"recommendation":{...}},"findings":[...]}error
Emitted if an error occurs while streaming. No done event follows.
interface ErrorResponse {
error: {
code: string; // Machine-readable error code
message: string; // Human-readable description
};
}Example:
event: error
data: {"error":{"code":"stream_error","message":"An unexpected error occurred."}}How is this guide?