Skip to main content
POST
/
api
/
v1
/
query
/
sandboxes
/
{sandbox_id}
/
search
Deep semantic search with synthesized answer
curl --request POST \
  --url https://api.copass.id/api/v1/query/sandboxes/{sandbox_id}/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "detail_level": "concise",
  "history": [],
  "max_tokens": 800,
  "preset": "fast",
  "query": "How does the Olane CLI surface Copass context to Claude Code?",
  "reference_date": "2026-04-16"
}
'
{
  "answer": "The Olane CLI installs a UserPromptSubmit hook that calls `copass discover` on every prompt, then renders the response as an ASCII tree for the user while also injecting the flat list as Claude-visible context.",
  "execution_time_ms": 1247,
  "preset": "fast",
  "query": "How does the Olane CLI surface Copass context to Claude Code?",
  "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
​
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

Retrieval mode. 'fast' (default) — low-latency agent-oriented; 'auto' — balanced quality; 'discover' — returns a menu of raw data chunks (one line per chunk) instead of a narrative answer; 'sql' — direct text-to-SQL over the ontology event store, rows instead of prose; 'max' — reserved, not available for public use (returns 403). Append '-decompose' to any of the above (e.g. 'sql-decompose') to split the question into sub-questions that run the base preset sequentially before synthesis.

Available options:
fast,
auto,
discover,
sql,
max,
fast-decompose,
auto-decompose,
discover-decompose,
sql-decompose
​
detail_level
enum<string>
default:concise

Amount of supporting context returned alongside the answer.

Available options:
concise,
detailed
​
max_tokens
integer | null

Cap on answer length. Accepts 100–16000; omit for the server default.

Required range: 100 <= x <= 16000

Response

Synthesized answer plus timing and any non-fatal warnings.

​
answer
string
required

Synthesized natural-language answer. On no-context / interpretation-failure paths this is a short status string — inspect warnings.

​
preset
string
required

Echo of the preset actually used (falls back to the server default when the request omitted preset).

​
execution_time_ms
integer
required

End-to-end wall time spent serving this request, in milliseconds.

Required range: x >= 0
​
sandbox_id
string
required

Echo of the sandbox this search ran against.

​
query
string
required

Echo of the caller's query.

​
warnings
string[] | null

Non-fatal signals describing why the answer may be thin: no_context (retrieval returned nothing), no_chunks (discover preset had no chunks to surface), interpretation_failed (LLM synthesis returned null).

​
project_id
string | null

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