> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Answer stream (RAG)

> Stream a RAG answer from the local LLM as Server-Sent Events.

## Overview

Same retrieval and prompting as [`POST /answer`](/api-references/answer), but the LLM response is streamed as **Server-Sent Events (SSE)** instead of a single JSON body.

When **no passages** are retrieved, the server **does not call the LLM**: you get one **`token`** event with *I don't have enough information to answer that question.* then **`done`** with `context_count: 0`.

Typical event order:

1. **`meta`** - model, sources, and context count (sent once)
2. **`token`** - one or more answer text deltas
3. **`done`** - full answer echo and metadata
4. **`error`** - if the LLM call fails (instead of `done`)

<Note>
  Requires Ollama running on the host. Start the stack with `moorcheh-edge up` (use `--skip-ollama` for search-only).
</Note>

## Request body

Same fields as [Answer (RAG)](/api-references/answer):

<ParamField body="query" type="string" required>
  Original question text (included in the LLM prompt and echoed in the response).
</ParamField>

<ParamField body="query_vector" type="array" required>
  JSON array of floats used for similarity search. Length must match the store **dimension** (768 for text stores).
</ParamField>

<ParamField body="top_k" type="number" default="5">
  Number of passages to retrieve for context. Capped at **100**.
</ParamField>

<ParamField body="threshold" type="number" default="0">
  Minimum search score when `kiosk_mode` is `true`.
</ParamField>

<ParamField body="kiosk_mode" type="boolean" default="false">
  When `true`, filters retrieved passages below `threshold`.
</ParamField>

<ParamField body="header_prompt" type="string">
  Optional system instruction (replaces the default RAG system prompt).
</ParamField>

<ParamField body="footer_prompt" type="string">
  Optional instruction appended before the user question in the final user message.
</ParamField>

<ParamField body="chat_history" type="array">
  Prior turns: `[{"role": "user"|"assistant", "content": "..."}]`.
</ParamField>

<ParamField body="temperature" type="number" default="0.2">
  LLM sampling temperature (0.0–2.0).
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -N -X POST "http://localhost:8080/answer/stream" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Who won the football match?",
      "query_vector": [0.01, -0.02, "... 768 floats ..."],
      "top_k": 5
    }'
  ```
</RequestExample>

<ResponseExample>
  ```text SSE theme={null}
  event: meta
  data: {"model":"qwen2.5:0.5b-instruct","context_count":1,"sources":[...],"query":"Who won the football match?"}

  event: token
  data: {"delta":"Manchester"}

  event: token
  data: {"delta":" United beat Chelsea 2-1."}

  event: done
  data: {"answer":"Manchester United beat Chelsea 2-1.","query":"Who won the football match?","model":"qwen2.5:0.5b-instruct","context_count":1}
  ```
</ResponseExample>

## SSE events

| Event   | When                | Data shape                                   |
| ------- | ------------------- | -------------------------------------------- |
| `meta`  | Once, before tokens | `model`, `context_count`, `sources`, `query` |
| `token` | Per LLM delta       | `{"delta": "..."}`                           |
| `done`  | Stream complete     | `answer`, `query`, `model`, `context_count`  |
| `error` | LLM failure         | `{"message": "..."}`                         |

The `sources` array in `meta` matches the shape returned by [`POST /search`](/api-references/search) (`id`, `score`, `label`, `text`).

## Errors

Non-streaming HTTP errors (empty store, invalid vector, LLM not configured) return JSON with a `4xx` status before SSE starts. Once streaming begins, LLM failures arrive as an SSE `error` event.

| Condition                | Status / event | Message (example)                                                          |
| ------------------------ | -------------- | -------------------------------------------------------------------------- |
| LLM not configured       | `400`          | `LLM is not configured: start Ollama on the host and run moorcheh-edge up` |
| LLM unreachable or error | SSE `error`    | `LLM request failed`                                                       |

## Related

* [Answer (RAG)](/api-references/answer)
* [Python: answer\_stream()](/python-client/answer-stream)
* [Voice server: POST /ask/stream](/api-references/voice-serve) - proxies this endpoint on edge hardware