Answer collection

Generate an answer with citations from files in one collection.

POST/namespaces/{namespace}/collections/{collection}:answer

PermissionCluster key, or a scoped key with query on this collection. Key scopes and actions.

Answer runs one retrieve-and-answer pass. effort is medium (the default) or high. Both allow 45 seconds, and 45 more with a query image. For deep, many-step work, start a research run. GET /info lists the supported efforts.
Send prior turns in history. Engine does not store conversations.
sources is a list in ref order: the cited sources first, in the order the answer first cites them, then the others by score. A marker such as [[SRC:0001]] in answer names the source whose ref is SRC:0001. sources: cited lists only the cited sources. sources: none returns an empty list and an answer with no markers.
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.

Request

https://engine.example.com/namespaces/acme/collections/incident-logs:answer

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

{
  "query": "What caused the database timeout?",
  "effort": "medium",
  "sources": "cited"
}

Replace engine.example.com with your cluster host. Examples use a key placeholder.

Response

200

An answer with source markers and its sources in ref order.

{
  "request_id": "req_example",
  "answer": "Checkout requests stalled because the database connection pool was exhausted [[SRC:0001]].",
  "effort": "medium",
  "sources": [
    {
      "ref": "SRC:0001",
      "span": {
        "file_id": "fil_01K6Q6N7D8E9F0G1H2J3K4M5N6",
        "unit": "chars",
        "start": 0,
        "end": 77
      },
      "path": "/reports/incident.txt",
      "content_type": "text/plain",
      "score": 0.81,
      "cited": true
    }
  ],
  "usage": {
    "credits": 1
  }
}

Path parameters

namespacestringrequired

Namespace name or ns_ ID. It must be visible to this key.

collectionstringrequired

Collection name or col_ ID within the namespace. It must be visible to this key.

Request body

effortstringoptional

medium (the default) or high. high reads more and takes longer. Both allow 45 seconds. For deep, many-step work, start a research run.

Default: "medium"

medium: One retrieve-and-answer pass. The default.
high: One retrieve-and-answer pass that reads more and takes longer.

filterFilterClauseoptionalaccepts null

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.

historyarray<object>optional

Prior conversation turns, oldest first. Maximum 32 messages. Your application stores and resends this history.

Maximum items: 32

instructionsstringoptionalaccepts null

Style instructions for the answer, such as its language, tone, or format. At most 8,000 characters. They replace the default answer style, not the rules for using sources.

Maximum characters: 8000

principalsarray<string>optionalaccepts null

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.

querystringrequired

Question to answer from this collection. Must contain non-space text and be at most 32,000 characters.

Minimum characters: 1
Maximum characters: 32000

query_imageobjectoptionalaccepts null

An image to ask about, read for this query only. Engine does not store or index it. Needs a cluster key, and adds 45 seconds to the time limit.

sourcesstringoptional

Which sources the response lists: all (default), cited, or none. none also removes the citation markers from the answer.

Default: "all"

all: List the cited sources first, then the other retrieved sources.
cited: List only the cited sources.
none: List no sources, and remove the citation markers from the answer.

Responses

200Success

An answer with source markers and its sources in ref order.

application/json

Response headers

x-engine-request-idstringrequired

The Engine request ID. Retain it when investigating a failed or unexpected request.

x-request-idstringrequired

The X-Request-Id you sent, echoed when it is a valid ID. Otherwise, the Engine request ID.

answerstringrequired

Answer text. A citation marker such as [[SRC:0001]] names the source whose ref is SRC:0001. The answer has no markers when the request sets sources to none.

effortstringrequired

The effort that produced this answer.

medium: One retrieve-and-answer pass. The default.
high: One retrieve-and-answer pass that reads more and takes longer.

image_descriptionstringoptionalaccepts null

How Engine read the query image. Null when the request had no image.

request_idstringrequired

The Engine request ID, also returned in the x-engine-request-id response header.

sourcesarray<object>required

The sources in ref order: the cited sources first, in the order the answer first cites them, then the others by score. Empty when the request sets sources to none.

usageobjectrequired

What the query used.

Errors

Select an error in the response example to see its JSON body. See error handling for the common error format.

400invalid_request

A field, path, parameter, or conditional request rule is invalid.

What to do: Correct the request. Unknown fields are rejected.

400invalid_filter

A filter uses an unsupported field, operator, value, or nesting structure, or a metadata key that the collection does not list. details.field names the field. details.reason is not_listed, op_not_allowed, or invalid_value for a metadata field.

What to do: Use the documented filter grammar and field-specific value types. List a metadata key with Update metadata fields before you filter on it.

401unauthenticated

The API key is missing, invalid, or revoked.

What to do: Send an active key in Authorization: Bearer or X-API-Key.

403forbidden

The key can see the resource but lacks permission for this operation.

What to do: Use a key with the required action or scope kind.

404not_found

The resource is absent, deleted, or outside this key’s scope.

What to do: Check the identifier and the key’s namespace and collection scope.

409collection_empty

The collection contains no living files to answer from.

What to do: Add a file and wait for a ready event before querying.

409collection_not_ready

The collection cannot serve this retrieval request yet.

What to do: Read retryable and details.retry_after_seconds. If processing failed, inspect file errors and correct the source.

413request_too_large

The JSON body exceeds the route limit: 6,291,456 bytes on :answer and research, 4,194,304 bytes on :search and :read-spans, and 1,048,576 bytes elsewhere.

What to do: Reduce the JSON body. Use upload or a URI source for larger file content.

503temporarily_unavailable

A dependency, cluster readiness condition, or capacity limit prevents this operation.

What to do: Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write.

500internal_error

An unexpected server failure prevented this request from completing.

What to do: Retain request_id for investigation. Follow retryable before retrying a write.

Was this page helpful?

View as Markdown