Skip to main content
POST
/
api
/
v1
/
query
/
sandboxes
/
{sandbox_id}
/
discover
Discover a typed menu of related context
curl --request POST \
  --url https://api.copass.id/api/v1/query/sandboxes/{sandbox_id}/discover \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "history": [
    {
      "content": "I'm evaluating Copass for our team.",
      "role": "user"
    },
    {
      "content": "Happy to help — what are you most curious about?",
      "role": "assistant"
    }
  ],
  "query": "What is the Copass Knowledge Graph?",
  "reference_date": "2026-04-16"
}
EOF
{
  "count": 1,
  "header": "## Discover: Relevant Context\n\nCandidate context from the user's knowledge graph that isn't in your current window. The items below are labels, not content — treat them as an index you must open before citing them.\n\n**How to use this response:**\n1. Scan for items that look relevant to the user's current question.\n2. Before answering from any item, call `interpret` with its `canonical_ids` tuple to read the actual content. A title alone is not evidence — do not describe or rely on an item without interpreting it first. Batch multiple items into a single `interpret` call.\n3. Use `search` as a fallback when nothing in the menu looks obviously relevant but the question still implies the graph holds the answer.\n4. Skip this menu entirely when the user's question is already answerable from conversation or code in your context.",
  "items": [
    {
      "canonical_ids": [
        "454494b2-6753-50b6-b659-6e4cf6a13391",
        "9c4c60c9-c404-5b9e-a69c-345593a44631"
      ],
      "id": "item_7c3f",
      "score": 0.87,
      "summary": "Olane CLI queries the Copass knowledge graph."
    }
  ],
  "next_steps": "If any item above plausibly relates to the user's question, call `interpret` on those canonical_ids before responding — titles are not evidence. `interpret` accepts multiple tuples in one call, so batch them: `interpret(items=[[<canonical_ids from item 1>], [<canonical_ids from item 2>], ...])`. Fall back to `search` only when no item looks relevant but the question still seems to need graph context. Skip both when the conversation already has what you need.",
  "query": "how does the CLI query the 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

Input for the discovery menu endpoint.

query
string
required

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

Required string length: 1 - 5000
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'.

Response

Ranked menu of candidate context items for the query.

items
DiscoveryItem · object[]
required

Ranked discovery items. Ordered by score descending — the caller picks one or more and passes their canonical_ids tuples to /interpret.

count
integer
required

Number of items in items. Convenience mirror so callers don't have to measure the array.

sandbox_id
string
required

Echo of the sandbox this discovery ran against.

query
string
required

Echo of the caller's query — useful when correlating async results without client-side state.

header
string
default:## Discover: Relevant Context Candidate context from the user's knowledge graph that isn't in your current window. The items below are labels, not content — treat them as an index you must open before citing them. **How to use this response:** 1. Scan for items that look relevant to the user's current question. 2. Before answering from any item, call `interpret` with its `canonical_ids` tuple to read the actual content. A title alone is not evidence — do not describe or rely on an item without interpreting it first. Batch multiple items into a single `interpret` call. 3. Use `search` as a fallback when nothing in the menu looks obviously relevant but the question still implies the graph holds the answer. 4. Skip this menu entirely when the user's question is already answerable from conversation or code in your context.

Markdown title + description orienting the caller on what this response contains and how to use it.

project_id
string | null

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

next_steps
string
default:If any item above plausibly relates to the user's question, call `interpret` on those canonical_ids before responding — titles are not evidence. `interpret` accepts multiple tuples in one call, so batch them: `interpret(items=[[<canonical_ids from item 1>], [<canonical_ids from item 2>], ...])`. Fall back to `search` only when no item looks relevant but the question still seems to need graph context. Skip both when the conversation already has what you need.

Short actionable pointer for what to do after picking items.