Skip to main content
POST
/
api
/
v1
/
query
/
sandboxes
/
{sandbox_id}
/
interpret
Summarize one discovery item with a macro-level brief
curl --request POST \
  --url https://api.copass.id/api/v1/query/sandboxes/{sandbox_id}/interpret \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "history": [
    {
      "content": "I'm evaluating Copass for our team.",
      "role": "user"
    }
  ],
  "items": [
    [
      "454494b2-6753-50b6-b659-6e4cf6a13391",
      "9c4c60c9-c404-5b9e-a69c-345593a44631"
    ],
    [
      "ef6964ec-900b-567f-8b43-ad813042b687"
    ]
  ],
  "query": "What is the Copass Knowledge Graph?",
  "reference_date": "2026-04-16"
}
EOF
{
  "brief": "The Copass Knowledge Graph is the ontology-backed store that the Olane CLI queries on every user prompt. It canonicalizes entities extracted from ingested data sources so downstream retrieval can pin on stable IDs rather than free-text labels.",
  "citations": [
    {
      "canonical_id": "9c4c60c9-c404-5b9e-a69c-345593a44631",
      "name": "Copass Knowledge Graph",
      "relevance": 0.91
    }
  ],
  "items": [
    [
      "454494b2-6753-50b6-b659-6e4cf6a13391",
      "9c4c60c9-c404-5b9e-a69c-345593a44631"
    ]
  ],
  "query": "What is the Copass Knowledge Graph?",
  "sandbox_id": "sbx_demo"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
authorization
string | null
​
X-Encryption-Token
string | null
​
X-Encryption-Key
string | null

Path Parameters

​
sandbox_id
string
required

Body

application/json
​
query
string
required

Current question. Typically the last user message in the conversation.

Required string length: 1 - 5000
​
items
string[][]
required

One or more tuples of canonical IDs to pin interpretation to. Pass the canonical_ids list from each DiscoveryItem you want to include — tuples are preserved so providers can use the grouping. Example: [["abc", "def"], ["ghi"]].

Minimum array length: 1
​
history
ChatMessage · object[]

Optional prior turns, oldest → newest. Server caps to the last 20 turns.

​
project_id
string | null

Storage project id to scope the retrieval against. Omit to span the entire sandbox.

​
reference_date
string | null

YYYY-MM-DD anchor for time-relative phrasing like 'last week'.

​
preset
enum<string> | null

Internal — retrieval preset override. Not part of the public contract yet; defaults to 'auto' when omitted. The 'max' value is reserved and will return 403.

Available options:
fast,
auto,
discover,
sql,
max

Response

A macro-level brief grounded in the pinned canonical tuples.

​
brief
string
required

A 1–2 paragraph macro-level summary synthesized from the pinned canonical tuples.

​
items
string[][]
required

Echo of the items tuples the caller sent, for correlation.

​
sandbox_id
string
required

Echo of the sandbox this interpretation ran against.

​
query
string
required

Echo of the caller's query.

​
citations
InterpretCitation · object[]

Up to 10 canonical entities that anchored the brief, ordered by relevance.

​
project_id
string | null

Echo of the project scope used, or null when the request spanned the full sandbox.