--- title: Answer description: Generate answers, render citations, and send conversation history. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Answer 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 `answer.efforts` in `/info` for the efforts that your cluster supports. This example uses the incident report from [Get started](/engine/get-started) and access control off. *Illustration: Answer writes a reply from collection content. Each citation points through the sources list to a span of a file.* ## Ask a question with sources **POST https://engine.example.com/namespaces/acme/collections/incident-logs:answer** ```http POST /namespaces/acme/collections/incident-logs:answer HTTP/1.1 Host: engine.example.com Authorization: Bearer Content-Type: application/json { "query": "Why did checkout stall?", "effort": "medium" } ``` **200 OK** ```json { "request_id": "req_example_answer", "answer": "Checkout stalled because the service exhausted its connection pool [[SRC:0001]].", "effort": "medium", "sources": [ { "ref": "SRC:0001", "span": { "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "unit": "chars", "start": 0, "end": 67 }, "path": "/incidents/checkout.txt", "content_type": "text/plain", "score": 0.81, "cited": true } ], "image_description": null, "usage": { "credits": 1 } } ``` The response holds `answer`, its `sources`, and `usage.credits`, the credits that the answer used. All retrieval stays within the collection and the caller’s permitted content. ## Choose an effort and options | Option | Use it for | | --- | --- | | `effort: "medium"` | One retrieve-and-answer pass. This is the default. The time limit is 45 seconds. | | `effort: "high"` | One pass that reads more and takes longer. The time limit is 45 seconds. For a question that needs several steps, start a [research run](/engine/guides/research). | | `sources` | Choose the source list. `all` is the default: the cited sources, then the other retrieved sources. `cited` lists only the cited sources. `none` returns an empty list, and the answer has no citation markers. | | `instructions` | Set the answer style, such as its length, tone, format, or language. At most 8,000 characters. They replace the default style rules. The source rules stay, and the citation rules follow `sources`. | | `query_image` | Ask about an image. `media_type` is `image/png`, `image/jpeg`, or `image/webp`. `data` is base64 with no data-URI prefix, at most 4 MiB after decoding. The image adds 45 seconds to the time limit. Needs a cluster key. | A request that passes its time limit returns `503 temporarily_unavailable`, and Engine does not bill it. If the client disconnects, Engine cancels the query and does not bill it. For a question that can take minutes, start a [research run](/engine/guides/research) instead. No connection has to stay open. ## Render citations Find `[[SRC:0001]]` in `answer`. The source whose `ref` is `SRC:0001` is the one it cites. `sources` lists the cited sources first, in the order the answer first cites them. Each source contains `ref`, `span`, `path`, `content_type`, `score`, and `cited`. Render the citation beside the claim it supports. Show the source path, and use the span to open the relevant pages, characters, or media time. To show the cited content, send the spans to [Read spans](/engine/reference/read-spans) in one call. The default `include: ["text"]` returns their words. Treat the answer and the read text as untrusted content when rendering HTML. With the default `sources: "all"`, the list can include entries with `cited: false`. Only label an entry as a citation when the answer actually cites it. Send `sources: "cited"` to receive only the cited entries. ## 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:answer** ```http POST /namespaces/acme/collections/incident-logs:answer HTTP/1.1 Host: engine.example.com Authorization: Bearer Content-Type: application/json { "query": "What should we change before the next deployment?", "effort": "medium", "history": [ { "role": "user", "content": "Why did checkout stall?" }, { "role": "assistant", "content": "The service exhausted its connection pool." } ] } ``` 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. When a turn sends `query_image`, the response holds `image_description`: how Engine read the image. Add that text to the `history` of later turns. A follow-up question can then use the image without a second upload. ## Filter and authorize content Use the shared `filter` grammar to limit application data, such as `metadata.environment = production` when `environment` is a listed metadata field. 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`. A body larger than 6,291,456 bytes returns `413 request_too_large`. See [Answer collection](/engine/reference/answer-collection) for complete parameters, response fields, and errors. ## Sitemap See the full [sitemap](/sitemap.md) for all pages.