Search & Answer

Two ways to query a tenant’s knowledge base. Both use the project’s API key and share the same request shape.

Request body

Field	Type	Default	Notes
`query`	string	—	required
`k`	integer	`5`	number of passages to return (1–50)
`graph_hops`	integer	`1`	graph traversal depth (0–2); `0` skips the graph and is fastest
`exclude_relations`	string[]	(unset)	relation types to drop from `edges` (case-insensitive). Unset ⇒ drop generic types (`MENTIONS`); `[]` ⇒ return the full graph; a list ⇒ your own exclusions

Search — retrieval only

POST /v1/search

Returns the ranked passages plus the retrieved subgraph. No synthesis.

curl -X POST https://api.your-host/v1/search \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund window", "k": 6}'

{
  "chunks":  [{ "chunk_id": "…", "document_id": "doc:…", "text": "…", "score": 0.78, "filename": "refunds.md" }],
  "entities": [{ "entity_id": "…", "name": "Refund Policy", "entity_type": "Concept", "description": "…" }],
  "edges":    [{ "source_id": "…", "target_id": "…", "relation_type": "PART_OF", "weight": 1.0 }],
  "graph_chunk_ids": []
}

chunks[].filename — the source document’s filename, for provenance (null if unresolved). Note document_id is the graph id (doc:<uuid>), a different id space from the id returned by GET …/documents — the two can’t be joined, so use filename for provenance.
edges — the subgraph around the retrieved chunks. Generic MENTIONS-type relations are omitted by default; use exclude_relations to change that. relation_type is drawn from a closed, per-ontology set.
graph_chunk_ids — passages recovered only via the graph (empty in the current configuration).

Answer — retrieval + synthesis

POST /v1/answer

Retrieves, then synthesizes an answer with citations validated against the supplied passages.

{
  "answer": "Refunds are issued within 14 days of purchase [chunk:doc:…:3].",
  "citations": [
    { "chunk_id": "chunk:doc:…:3", "document_id": "doc:…", "text": "…", "filename": "refunds.md", "source": "retrieval" }
  ],
  "graph_used": false,
  "graph_chunk_ids": []
}

citations — the passages the answer actually used; each resolves to a real chunk in your corpus.
graph_used — whether graph context reached the answer (false while graph answering is disabled).
graph_chunk_ids — passages recovered specifically via the graph (empty unless graph retrieval is on).

If nothing supports the question, the model declines rather than inventing an answer.

Streaming

POST /v1/answer/stream

Same request; the answer is streamed as Server-Sent Events. Each event is data: {"t": "<token>"}, and the stream ends with data: [DONE].

← PreviousDocuments & Jobs Next →Self-hosting