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

# Query

> Query the knowledge base with natural language

Query the Vrin knowledge base. Returns an AI-generated answer backed by knowledge graph facts and vector search results.

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer vrin_live_abc123`
</ParamField>

<ParamField body="query" type="string" required>
  Natural-language question to answer.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  If `true`, the response is delivered as Server-Sent Events (SSE). Each event contains a JSON object with `type` and `data` fields.
</ParamField>

<ParamField body="response_mode" type="string" default="chat">
  Answer depth: `"chat"` (concise), `"thinking"` (reasoning chains), `"research"` (exhaustive multi-hop).
</ParamField>

<ParamField body="query_depth" type="string">
  Override retrieval depth: `"basic"`, `"thinking"`, `"research"`.
</ParamField>

<ParamField body="model" type="string">
  LLM model override (e.g. `"gpt-4o"`).
</ParamField>

<ParamField body="session_id" type="string">
  Conversation session ID to continue.
</ParamField>

<ParamField body="maintain_context" type="boolean" default="false">
  If `true`, maintain conversation context. A `session_id` will be returned in the response.
</ParamField>

<ParamField body="include_summary" type="boolean" default="true">
  If `true`, include AI-generated summary. Set to `false` for raw fact retrieval only.
</ParamField>

<ParamField body="web_search_enabled" type="boolean" default="false">
  Enable web search augmentation.
</ParamField>

<ParamField body="conversation_upload_ids" type="string[]">
  Upload IDs to include as additional context.
</ParamField>

### Non-streaming response

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "summary": "ACME Corp reported $50M revenue in Q4 2025, representing a 23% increase year-over-year. CEO Jane Smith attributed the growth to the enterprise segment.",
    "session_id": "sess_abc123",
    "total_facts": 12,
    "total_chunks": 5,
    "metadata": {
      "entities": ["ACME Corp", "Jane Smith"],
      "model": "gpt-4o-mini",
      "search_time": "1.2s"
    }
  }
  ```
</ResponseExample>

### Streaming response (SSE)

When `stream: true`, the response is `text/event-stream`:

```
data: {"type": "metadata", "data": {"session_id": "sess_abc123", "total_facts": 12, "entities": ["ACME Corp"]}}

data: {"type": "content", "data": {"delta": "ACME Corp "}}

data: {"type": "content", "data": {"delta": "reported $50M "}}

data: {"type": "sources", "data": {"sources": [{"title": "ACME Q4 Earnings", "chunk_id": "c_123"}]}}

data: {"type": "done", "data": {}}
```

### SSE event types

| Type        | Data fields                                                      | Description                    |
| ----------- | ---------------------------------------------------------------- | ------------------------------ |
| `metadata`  | `session_id`, `total_facts`, `total_chunks`, `entities`, `model` | Retrieval metadata, sent first |
| `content`   | `delta`                                                          | Text token                     |
| `reasoning` | `chains` or `steps`                                              | Reasoning chain steps          |
| `sources`   | `sources`                                                        | Source document references     |
| `done`      | `error?`, `insufficient_coverage?`                               | Stream complete                |
| `error`     | `message`                                                        | Fatal error                    |

### Insufficient coverage

When the knowledge base has no relevant facts, the response includes `insufficient_coverage: true` and skips LLM generation.

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "summary": "",
    "insufficient_coverage": true,
    "total_facts": 0,
    "total_chunks": 0
  }
  ```
</ResponseExample>