Answer

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 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?",
  "effort": "medium"
}

{
  "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

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