--- title: Query collection description: Generate an answer with citations from files in one collection. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Query collection `POST /namespaces/{namespace}/collections/{collection}:query` Generate an answer with citations from files in one collection. **Permission:** Cluster key, or a scoped key with query on this collection. [API key types and authentication](/engine/reference/authentication.md). standard uses one retrieve-and-answer pass. ultra performs deeper work within the collection. Check GET /info for supported modes. Send prior turns in history. Engine does not store conversations. Answer markers such as [[SRC:0001]] match [SRC:0001] keys in sources. return_sources: false omits that map. Send principals only when access_control is enforced. Access rules bound every source used for the answer. An empty collection returns collection_empty. A failed collection returns collection_not_ready with retryable: false. ## Example request ```http POST /namespaces/acme/collections/incident-logs:query HTTP/1.1 Host: engine.example.com Authorization: Bearer Content-Type: application/json { "query": "What caused the database timeout?", "mode": "standard", "return_sources": true } ``` ## Path parameters ### `namespace` **string · required** Namespace name or ns_ ID. It must be visible to this key. ### `collection` **string · required** Collection name or col_ ID within the namespace. It must be visible to this key. ## Request body ### `filter` **FilterClause · optional · nullable** Structured selection of files to use for the answer. Uses the same grammar as Search. Filters do not replace access rules. - Maximum depth: 8 - Maximum clauses: 100 - An in list holds 1–100 values. #### Comparison Compare one built-in or metadata field. ##### `filter.field` **string · required** path, content_type, bytes, created_at, updated_at, status, or metadata.. Metadata keys have 1–256 characters. ##### `filter.op` **string · required** Comparison operator. Strings support eq, neq, prefix, and in. bytes supports numeric comparisons and in. Timestamps support comparisons. status supports eq, neq, and in. - `eq`: Equal. - `neq`: Not equal. - `gt`: Greater than. - `gte`: Greater than or equal. - `lt`: Less than. - `lte`: Less than or equal. - `prefix`: String starts with this value. - `in`: Equal to one value in a nonempty array. ##### `filter.value` **JSON scalar | array · required** Value of the correct type for the field. bytes uses non-negative integers. Timestamps need an ISO 8601 timezone. in takes an array. Metadata equality accepts string, number, boolean, or null. #### All clauses ##### `filter.and` **array · required** Nonempty list of clauses that must all match. Each entry uses this same FilterClause grammar. #### Any clause ##### `filter.or` **array · required** Nonempty list of clauses where at least one must match. Each entry uses this same FilterClause grammar. #### Negated clause ##### `filter.not` **FilterClause · required** One clause that must not match. It uses this same FilterClause grammar. ### `history` **array · optional** Prior conversation turns, oldest first. Maximum 32 messages. Your application stores and resends this history. - Maximum items: 32 #### `history[].content` **string · required** Text of this previous conversation turn. Maximum 32,000 characters. - Maximum characters: 32000 #### `history[].role` **string · required** Speaker of this prior turn: user or assistant. Engine does not store a conversation. - `user`: A previous user message. - `assistant`: A previous assistant answer. ### `mode` **string · optional** Answer mode. standard performs one retrieve-and-answer pass. ultra performs deeper work within the collection. Check GET /info for supported modes. Default: `"standard"`. - `standard`: One retrieve-and-answer pass, with a 120-second limit. - `ultra`: Deeper work within the collection, with a 600-second limit. ### `principals` **array · optional · nullable** End-user and group identifiers supplied by your server. Required on enforced collections and invalid when access control is off. An empty list gives no results. Maximum 4,096 entries, each at most 256 UTF-8 bytes. ### `query` **string · required** Question to answer from this collection. Must contain non-space text and be at most 32,000 characters. - Minimum characters: 1 - Maximum characters: 32000 ### `return_sources` **boolean · optional** Include the source map for citations. When false, the response omits sources. Default: `true`. ## Responses ### 200 · Success An answer with source markers and their matching source map. Content type: `application/json`. #### Response headers ##### `x-request-id` **string · required** Request correlation ID. Retain it when investigating a failed or unexpected request. ```json { "request_id": "req_example", "answer": "Checkout requests stalled because the database connection pool was exhausted [[SRC:0001]].", "mode": "standard", "sources": { "[SRC:0001]": { "file_id": "fil_01K6Q6N7D8E9F0G1H2J3K4M5N6", "path": "/reports/incident.txt", "score": 0.81, "is_cited": true, "evidence": { "kind": "text", "text": "Checkout requests stalled because the database connection pool was exhausted.", "location": { "char_start": 0, "char_end": 77 } } } } } ``` #### Response fields ##### `answer` **string · required** Answer text. Citation markers use [[SRC:0001]] and match the [SRC:0001] keys in sources. ##### `mode` **string · required** Query mode that produced this answer. - `standard`: One retrieve-and-answer pass, with a 120-second limit. - `ultra`: Deeper work within the collection, with a 600-second limit. ##### `request_id` **string · required** Correlation ID for this request, also available in x-request-id. ##### `sources` **map · optional · nullable** Map from citation markers to supporting sources. Keys omit the marker’s outer brackets. Omitted when return_sources is false. ###### `sources[key].evidence` **object · required** One source excerpt with its kind and optional position. ###### `sources[key].evidence.kind` **string · required** Form of the extracted evidence, such as text, transcript, OCR, or a page. - `text`: Extracted text. - `transcript`: Transcript from audio or video. - `ocr`: Text recognized from an image or document page. - `json_path`: Evidence at a JSON path. - `page`: Evidence from a document page. - `image_region`: Evidence from a region of an image. ###### `sources[key].evidence.location` **object · optional · nullable** Position of this evidence within the source. The fields depend on its location type. Omitted when no position is available. ###### TimeSpan ###### `sources[key].evidence.location.end_ms` **integer · required** End of the source excerpt, in milliseconds from the beginning of the audio or video. ###### `sources[key].evidence.location.start_ms` **integer · required** Start of the source excerpt, in milliseconds from the beginning of the audio or video. ###### Page ###### `sources[key].evidence.location.bbox` **array · optional · nullable** Optional bounding box coordinates for a region on the referenced page. ###### `sources[key].evidence.location.page` **integer · required** Page number identifying the evidence in the source. ###### JsonPath ###### `sources[key].evidence.location.json_path` **string · required** JSON path locating the evidence within a structured source. ###### CharSpan ###### `sources[key].evidence.location.char_end` **integer · required** End character offset of the evidence within extracted text. ###### `sources[key].evidence.location.char_start` **integer · required** Start character offset of the evidence within extracted text. ###### `sources[key].evidence.text` **string · required** Extracted source text supporting this match or citation. ###### `sources[key].file_id` **string · required** ID of the source file within the queried collection. ###### `sources[key].is_cited` **boolean · required** Whether the answer cites this source marker. ###### `sources[key].path` **string · required** Logical path of the source file within the collection. ###### `sources[key].score` **number · required** Ranking value for this result. It is not a confidence percentage. ## Errors [Error format and retry guidance](/engine/reference/errors.md). ### 400 · `invalid_request` A field, path, parameter, or conditional request rule is invalid. Correct the request. Unknown fields are rejected. ```json { "error": { "code": "invalid_request", "message": "A field, path, parameter, or conditional request rule is invalid.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 400 · `invalid_filter` A filter uses an unsupported field, operator, value, or nesting structure. Use the documented filter grammar and field-specific value types. ```json { "error": { "code": "invalid_filter", "message": "A filter uses an unsupported field, operator, value, or nesting structure.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 401 · `unauthenticated` The API key is missing, invalid, or revoked. Send an active key in Authorization: Bearer or X-API-Key. ```json { "error": { "code": "unauthenticated", "message": "The API key is missing, invalid, or revoked.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 403 · `forbidden` The key can see the resource but lacks permission for this operation. Use a key with the required action or scope kind. ```json { "error": { "code": "forbidden", "message": "The key can see the resource but lacks permission for this operation.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 404 · `not_found` The resource is absent, deleted, or outside this key’s scope. Check the identifier and the key’s namespace and collection scope. ```json { "error": { "code": "not_found", "message": "The resource is absent, deleted, or outside this key’s scope.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 409 · `collection_empty` The collection contains no living files to answer from. Add a file and wait for a ready event before querying. ```json { "error": { "code": "collection_empty", "message": "The collection contains no living files to answer from.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 409 · `collection_not_ready` The collection cannot serve this retrieval request yet. Read retryable and details.retry_after_seconds. If processing failed, inspect file errors and correct the source. ```json { "error": { "code": "collection_not_ready", "message": "The collection cannot serve this retrieval request yet.", "request_id": "req_example", "retryable": true, "details": { "retry_after_seconds": 30 } } } ``` ### 413 · `request_too_large` The JSON request body exceeds 1,048,576 bytes. Reduce the JSON body. Use upload or a URI source for larger file content. ```json { "error": { "code": "request_too_large", "message": "The JSON request body exceeds 1,048,576 bytes.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 503 · `temporarily_unavailable` A dependency, cluster readiness condition, or capacity limit prevents this operation. Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write. ```json { "error": { "code": "temporarily_unavailable", "message": "A dependency, cluster readiness condition, or capacity limit prevents this operation.", "request_id": "req_example", "retryable": true, "details": {} } } ``` ### 500 · `internal_error` An unexpected server failure prevented this request from completing. Retain x-request-id for investigation. Follow retryable before retrying a write. ```json { "error": { "code": "internal_error", "message": "An unexpected server failure prevented this request from completing.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ## Other request languages ### cURL ```bash curl -sS -X POST "$GRAPHON_ENGINE_URL/namespaces/acme/collections/incident-logs:query" \ -H "Authorization: Bearer $GRAPHON_ENGINE_API_KEY" \ -H 'Content-Type: application/json' \ --data-raw '{ "query": "What caused the database timeout?", "mode": "standard", "return_sources": true }' ``` ### Python ```python import json import os import urllib.request request = urllib.request.Request( os.environ["GRAPHON_ENGINE_URL"] + "/namespaces/acme/collections/incident-logs:query", data=json.dumps({"query": "What caused the database timeout?", "mode": "standard", "return_sources": True}).encode("utf-8"), headers={ "Authorization": "Bearer " + os.environ["GRAPHON_ENGINE_API_KEY"], "Content-Type": "application/json", }, method="POST", ) with urllib.request.urlopen(request) as response: print(response.read().decode()) ``` ### JavaScript ```javascript const response = await fetch(process.env.GRAPHON_ENGINE_URL + "/namespaces/acme/collections/incident-logs:query", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GRAPHON_ENGINE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({"query":"What caused the database timeout?","mode":"standard","return_sources":true}), }); console.log(response.status, await response.text()); ``` ## Sitemap See the full [sitemap](/sitemap.md) for all pages.