Answer (streaming)
The same grounded answer as /v1/answer, delivered as a Server-Sent Events stream — token deltas as they generate, then a terminal frame with citations.
Identical retrieval, policy binding, and grounding to
/v1/answer — but the response is a Server-Sent Events
stream instead of a single JSON body. A chat widget renders tokens as they
arrive instead of waiting for the whole composition, which is the difference
between a spinner and a live-typing assistant.
Request body
Exactly the same as /v1/answer (query, surface, channel,
mode, topK, onBehalfOf, history).
{
"query": "how long does porting take?",
"surface": "site_chatbot",
"channel": "chat"
}Response — text/event-stream
A sequence of SSE frames. Each frame has an event: name and a data: line of
JSON. The stream always ends with exactly one done (success) or error.
Prop
Type
event: token
data: {"delta":"Port"}
event: token
data: {"delta":"ing usually takes 2–3 business days. [1]"}
event: done
data: {"citations":[{"docId":"website/porting","sourceSystem":"website","snippet":"Porting typically takes 2–3 business days…","score":0.79}],"decisionId":"dec_a71b…","snapshotId":"snap_v3_10421_b17","usedChunkIds":["chunk:port_faq_2"]}Errors that occur before the stream opens (bad key, invalid body) are
ordinary JSON error replies with a 4xx status — see Errors.
Once the stream is open the status is already 200, so a mid-stream failure
arrives as a terminal error frame instead.
Consuming it
The @molecule/sdk exposes this as an async iterator — no manual SSE
parsing:
for await (const ev of molecule.answerStream("how long does porting take?", {
surface: "site_chatbot",
})) {
if (ev.type === "token") process.stdout.write(ev.delta);
else if (ev.type === "done") console.log(ev.citations);
else if (ev.type === "error") console.error(ev.error);
}Raw curl (watch the frames arrive):
curl -N -X POST http://localhost:8080/v1/answer/stream \
-H "Authorization: Bearer sa_demo_public_key" \
-H "Content-Type: application/json" \
-d '{ "query": "what are your pricing plans?", "surface": "site_chatbot" }'In mock mode the stream is the deterministic canned answer split into word-sized
deltas — enough to wire up and test the streaming UI. Set AI_PROVIDER=openai
for real token streaming from the model.