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

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": "…", "text": "…", "score": 0.78 }],
  "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": []
}

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": "…", "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].