Answer

Before you begin

Use a collection with ready files and a key with query access. Check query.modes in /info for the modes that your cluster supports. This example uses the incident report from Get started and access control off.

Ask a question with sources

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": "Why did checkout stall?",
  "mode": "standard",
  "return_sources": true
}

{
  "request_id": "req_example_answer",
  "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
        }
      }
    }
  },
  "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 a mode and options

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 instead. A research run takes the same body, and no connection has to stay open.

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 /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 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.

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. 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 for complete parameters, response fields, and errors.