Chat (SSE) - BeforeQuery

Stream a citation-backed answer for a user’s question.

POST https://api.agents.beforequery.com/api/v1/public/knowledge-bases/:knowledgeBaseId/chat

Auth: client key. Response: text/event-stream.

Request body

Field	Type	Required	Description
`query`	`string`	Yes	The user’s question
`thread_id`	`string`	No	Continue an existing conversation thread
`group_ids`	`string[]`	No	Scope retrieval to source groups; intersected with the key’s `allowed_groups` (403 if a group is outside the knowledge base or the allowed set)
`user`	`{ email?, id? }`	No	End-user identity for analytics

curl -N https://api.agents.beforequery.com/api/v1/public/knowledge-bases/kb_xxx/chat \
  -H "X-Client-Key: bq_pk_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "How does OAuth work?"}'

Response stream

Frames are unnamed SSE events — every line is data: carrying a JSON object. There are no event: names, so a client reads message events and branches on the fields present.

data: {"delta":"OAuth in ","done":false}

data: {"delta":"this product uses ...","done":false}

data: {"citations":[{"index":1,"url":"https://docs.example.com/oauth","title":"OAuth Guide","document_id":"doc_uuid"}],"done":false}

data: {"done":true,"thread_id":"thr_uuid","message_id":"msg_uuid"}

Field	Present on	Description
`delta`	token frames	The next chunk of answer text — append it
`citations`	one frame, before `done`	Sources for the answer
`done`	every frame	`false` while streaming, `true` on the final frame
`thread_id`	final frame	Pass it back to continue the conversation
`message_id`	final frame	For feedback. Absent when the workspace has zero-data-retention, since there’s no stored message to rate
`error`	instead of a final frame	A user-facing failure message

const res = await fetch(url, { method: "POST", headers, body });
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let answer = "";

for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  for (const line of value.split("\n")) {
    if (!line.startsWith("data: ")) continue;
    const frame = JSON.parse(line.slice(6));
    if (frame.error) throw new Error(frame.error);
    if (frame.delta) answer += frame.delta;
    if (frame.citations) render(frame.citations);
    if (frame.done) return { answer, threadId: frame.thread_id, messageId: frame.message_id };
  }
}

Citations map to [n] markers in the answer text — render them as numbered source links.

The dashboard’s own POST /api/v1/chat uses the same frame shape but names the thread conversation_id rather than thread_id.

Continuing a conversation

Either pass thread_id in the knowledge base chat body, or post to the thread endpoint:

POST https://api.agents.beforequery.com/api/v1/public/threads/:threadId/chat

Same body and stream format. Conversation memory includes recent turns, so follow-ups like “what about SSO?” resolve correctly.

CAPTCHA

Public keys must include X-Captcha-Token: <reCAPTCHA v3 token> whenever reCAPTCHA is configured on the server. See Authentication.

Notes

Restricted documents are never retrieved by public chat.
When retrieval finds nothing relevant, the assistant says it doesn’t know rather than guessing — answers are generated only from retrieved sources.
Prefer WebSocket? See the WebSocket transport — the SDK uses it by default with SSE fallback.

​Request body

​Response stream

​Continuing a conversation

​CAPTCHA

​Notes

Request body

Response stream

Continuing a conversation

CAPTCHA

Notes