Asking questions & streaming

The full POST /v1/query request shape, generation overrides, and the SSE streaming events.

POST /v1/query is the generated-answer surface: same permission-aware retrieval as /v1/retrieve, plus a grounded, cited answer synthesized from what it finds.

Minimal request

curl -s https://apibr.aize.dev/v1/query \
  -H "Authorization: Bearer $BRAIZE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "What is our refund policy?"}'

Request fields

Field	Default	Meaning
`text`	— (required)	The question, up to 4000 characters.
`conversation_id`	new conversation	Continue an existing conversation instead of starting one.
`stream`	`false`	`true` switches the response to `text/event-stream` (see below).
`model`	`chat-default`	`chat-default` \| `chat-strong` \| `chat-fast`. Unknown aliases fail with a 422 `invalid-request`.
`temperature`	`0`	0–2.
`top_k`	`12`	Max context chunks assembled for the answer.
`answer_mode`	`balanced`	`fast` (quicker, lighter checks) \| `balanced` (default, cache-eligible) \| `thorough` (extra retry budget, full groundedness check). An explicit `model`/`temperature`/`top_k` overrides the mode's preset for that knob.
`system_prompt`	none	Appended to (never replacing) Braize's grounded system prompt — citation and numeric-fidelity rules always win.

Any override present bypasses the answer cache for that request (read and write); balanced with everything else at default stays cache-eligible.

Response

{
  "data": {
    "conversation_id": "…",
    "confidence": 0.92,
    "blocks": [
      { "type": "citation", "document_id": "…", "title": "Refund Policy", "url": "…", "excerpt": "…" }
    ]
  },
  "meta": { "request_id": "…", "braize_version": "2026-09-01" }
}

data.blocks is a discriminated union (type: "citation" | "text") — citation blocks always come back; a text block (the generated prose) is included only when your workspace has include_generated_answers turned on. Treat unknown block types as forward-compatible additions, not errors. data.confidence is 0–1; when the knowledge base doesn't cover the question, Braize says so rather than guessing — check for a low confidence and an empty/thin block list rather than assuming every response is a confident answer.

Streaming (`"stream": true`)

The response becomes text/event-stream. Each event's data: payload matches the schema named by its event: field:

Event	Payload
`answer.delta`	`{ "text": "…" }` — the next fragment of answer text.
`answer.citation`	`{ "block": { ...CitationBlock }, "anchor_offset": 128 }` — a citation attaching to a character offset in the accumulated text.
`answer.done`	Stream complete.
`error`	An inline Problem-shaped payload — see Handling errors.

Clients must skip unknown event names — new event types are additive forever. See the full schemas in the API reference.

What's next

Agent-native retrieval — skip generation entirely and get ranked passages instead.
Rate limits & quotas — every /v1/query call counts against your monthly query cap.