---
title: Query
description: Generate answers, render citations, and send conversation history.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Query

Ask a question about one collection and render an answer with citations. Keep conversation history in your application and pass the context needed for each turn.

## Before you begin

Use a collection with ready files and a key with `query` access. Check `/info` for available Query modes. This example uses the incident report from [Get started](/engine/get-started) and access control off.

*Illustration: Query writes an answer from collection content. Each citation points through the sources map to a file and its supporting evidence.*

## Ask a question with sources

**POST https://engine.example.com/namespaces/acme/collections/incident-logs:query**

```http
POST /namespaces/acme/collections/incident-logs:query HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json

{
  "query": "Why did checkout stall?",
  "mode": "standard",
  "return_sources": true
}
```

**200 OK**

```json
{
  "request_id": "req_example_query",
  "answer": "Checkout stalled because the service exhausted its connection pool [[SRC:0001]].",
  "mode": "standard",
  "sources": {
    "[SRC:0001]": {
      "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
      "path": "/incidents/checkout.txt",
      "score": 0.81,
      "is_cited": true,
      "evidence": {
        "kind": "text",
        "text": "Checkout stalled because the service exhausted its connection pool.",
        "location": {
          "char_start": 0,
          "char_end": 67
        }
      }
    }
  }
}
```

Use `standard` for the default retrieve-and-answer flow. Use `ultra` for deeper retrieval when `/info` lists it. All retrieval stays within the collection and the caller’s permitted content.

## Render citations

Find `[[SRC:0001]]` in `answer`. Remove one outer bracket pair and use `[SRC:0001]` as the key in `sources`. The source contains `file_id`, `path`, `score`, `is_cited`, and one evidence object.

Render the citation beside the claim it supports. Show the source path and evidence text. Use the location to open the relevant page, text span, JSON value, or media time. Treat the answer and source text as untrusted content when rendering HTML.

A source map can include entries with `is_cited: false`. Only label an entry as a citation when the answer actually cites it. `return_sources` defaults to true. Setting it to false omits `sources`, so keep it true for a citation interface.

## Continue a conversation

Store prior turns in your application. On the next request, send them in `history`, oldest first. Each item has `role: "user"` or `role: "assistant"` and a `content` string. Put the new question in `query`.

**POST https://engine.example.com/namespaces/acme/collections/incident-logs:query**

```http
POST /namespaces/acme/collections/incident-logs:query HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json

{
  "query": "What should we change before the next deployment?",
  "mode": "standard",
  "history": [
    {
      "role": "user",
      "content": "Why did checkout stall?"
    },
    {
      "role": "assistant",
      "content": "The service exhausted its connection pool."
    }
  ],
  "return_sources": true
}
```

A history can contain at most 32 messages. Each message and the new question can contain at most 32,000 characters. Engine returns an answer for this call and does not save a chat thread.

## Filter and authorize content

Use the shared `filter` grammar to limit application data, such as `metadata.environment = production`. On an enforced collection, send the reader’s trusted `principals` list as well. Filters cannot replace access rules.

A `409 collection_empty` means the collection has no files. `409 collection_not_ready` means no usable content is ready. If `retryable` is false, correct the failed files before retrying. An unavailable mode returns `400 invalid_request`.

See [Query collection](/engine/reference/query-collection) for complete parameters, response fields, and errors.
## Sitemap

See the full [sitemap](/sitemap.md) for all pages.