Streaming responses
Four calls can take seconds to minutes, so they answer with server-sent events instead of one JSON body:
| Call | Events, in order |
|---|---|
POST /v1/ask |
generating, running (once per attempt), then answer or error |
POST /v1/uis |
generating, checking (once per attempt), then ui or error |
POST /v1/uis/{id}/versions |
the same as POST /v1/uis |
POST /v1/chat |
routing, routed, then either reply, or the events of the flow the message was routed to |
The format
Section titled “The format”The response has Content-Type: text/event-stream. Each event is an event: line and a data: line holding
one line of JSON, followed by an empty line:
event: runningdata: {"attempt":1}While the API waits on the language model it sends a comment line (: keep-alive) every 15 seconds, so
proxies don’t close an idle connection. Ignore lines that start with :.
The data of each event is described in the reference: AskEvent, UiEvent and ChatEvent list every event
with its fields.
Errors
Section titled “Errors”- Before the stream starts (not logged in, not allowed, invalid body, rate limited, the model not configured), the call answers with a normal status code and the JSON error shape.
- After it starts, the status is already
200: a failure arrives as anerrorevent with acodeand amessage, and the stream ends. The codes are listed under stream error codes.
Reading a stream
Section titled “Reading a stream”EventSource cannot send a POST body, so read the response with fetch:
const res = await fetch('https://api.dev.loupestack.com/v1/ask', { method: 'POST', credentials: 'include', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ question: 'How many customers do we have?' }),});if (!res.ok) throw new Error((await res.json()).error.code); // failed before the stream started
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();let buffer = '';for (;;) { const { value, done } = await reader.read(); if (done) break; buffer += value; let end; while ((end = buffer.indexOf('\n\n')) >= 0) { const block = buffer.slice(0, end); buffer = buffer.slice(end + 2); const event = block.match(/^event: (.*)$/m)?.[1]; const data = block.match(/^data: (.*)$/m)?.[1]; if (event && data) console.log(event, JSON.parse(data)); }}With curl, pass -N so it prints events as they arrive (Quickstart).
Stopping
Section titled “Stopping”Close the connection to stop: the API stops working on that request and frees its share of the workspace’s limits. A question ends after at most 60 seconds, a UI generation after 10 minutes.
Conversations
Section titled “Conversations”answer, reply and the first events carry a conversationId. Send it with the next question or chat
message to continue the same conversation; GET /v1/conversations
lists them.