Streaming

Set "stream": true on Query or Send Message to receive the response as a text/event-stream of named Server-Sent Events.

cURL

curl -N -X POST https://api.doctly.ai/api/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection_ids": ["..."], "query": "What is the warranty period?", "stream": true}'

Events

Each SSE frame carries an event name and a JSON data payload.

`status`

Progress updates while the answer is being researched.

event: status
data: {"step": "retriever", "heading": "Searching your documents"}

`delta`

Incremental answer text. Concatenate text values in order to build the running answer.

event: delta
data: {"text": "The warranty period is "}

`complete`

Terminal event with the final answer and citations. For session messages it also carries the stored message id and session_id.

event: complete
data: {"id": 42, "session_id": "b31c9a52-...", "answer": "The warranty period is 24 months [citation:3:12].", "citations": [...]}

`error`

Terminal event when generation fails mid-stream.

event: error
data: {"error": {"type": "api_error", "message": "..."}}

Keepalives

During long retrieval steps the stream emits SSE comment lines (: keepalive). Standards-compliant SSE parsers discard comments automatically; no handling is needed.

Consuming the stream

The final delta-accumulated text may differ slightly from the complete event’s answer (the complete answer is authoritative). Always end on complete or error; if the connection drops earlier, the partial assistant message is stored with status: "partial" and can be fetched via Get Messages.

API Overview

Documents

Extractors

Collections

Collection Files

Chat

Events

`status`

`delta`

`complete`

`error`

Keepalives

Consuming the stream

​Events

​status

​delta

​complete

​error

​Keepalives

​Consuming the stream

Events

`status`

`delta`

`complete`

`error`

Keepalives

Consuming the stream