Search & ask

Two endpoints answer questions about the knowledge base, at two different altitudes. GET /api/v1/search hands you the raw chunks — scored, ranked, no model in the loop — for you to render or feed into your own reasoning. POST /api/v1/query runs the whole pipeline and hands back a grounded, dual-cited answer. Pick by whether you or eli.ai does the synthesis.

Prerequisites

• A key with kb:read for /search. /query invokes the chat model, so it needs agents:run. See Getting started.
• For /query, an enabled chat model in the workspace — otherwise 409 no-model-configured.

Raw chunks — GET /search

Hybrid retrieval — full-text and vector fused — over the workspace's documents. No LLM call, so it is fast and cheap, and you get the underlying evidence unedited: chunk text, the document it came from, and a relevance score. Use it to build your own search UI, to power autocomplete, or as the retrieval step in a pipeline you control.

curl -s "https://your-host/api/v1/search?q=order%20platform%20stuck%20orders&limit=2&rerank=true" \
  -H "Authorization: Bearer $ELI_KEY"

{
  "results": [
    {
      "chunkId": "01KY10BBBBBBBBBBBBBBBBBBBB",
      "docId": "01KY10AAAAAAAAAAAAAAAAAAAA",
      "docTitle": "Order Platform incident runbook",
      "docPath": "ops/order-platform-runbook.md",
      "score": 0.8134,
      "snippet": "When orders remain in STUCK status for more than 24 hours, requeue them from the fulfillment console…"
    },
    {
      "chunkId": "01KY10DDDDDDDDDDDDDDDDDDDD",
      "docId": "01KY10AAAAAAAAAAAAAAAAAAAA",
      "docTitle": "CFO interview — March 2026",
      "docPath": "northwind/interviews/cfo-2026-03.md",
      "score": 0.6421,
      "snippet": "The Order Platform migration is the top cost driver this quarter…"
    }
  ],
  "query": "order platform stuck orders"
}

By default /search returns the raw reciprocal-rank-fused order — cheapest, and model-free. Pass ?rerank=true to have the fused candidates cross-encoder-reranked server-side before they come back, when precision matters more than the extra round-trip. It is a no-op (and free) if the workspace reranker resolves to none. The full pipeline behind grounded answers — query understanding, graph fusion, and a token-budget assembler on top of that rerank — is described in Retrieval pipeline.

Grounded answer — POST /query

The full pipeline in one call: retrieval, deterministic entity detection, one chat-model generation, and a best-effort groundedness check. You get an answer with inline [Sn] citation markers, the answer decomposed into atomic claims, and a sources registry mapping each marker back to the exact chunk. With includeData: true it also runs governed live-data lookups and adds [Dn] data citations — see Query live data.

curl -s -X POST https://your-host/api/v1/query \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"How do we handle stuck orders on the Order Platform?"}'

{
  "answer": "Stuck orders older than 24 hours should be requeued from the fulfillment console per the incident runbook [S1].",
  "claims": [
    { "text": "Stuck orders older than 24 hours should be requeued from the fulfillment console", "citations": ["S1"] }
  ],
  "sources": [
    {
      "id": "S1",
      "docId": "01KY10AAAAAAAAAAAAAAAAAAAA",
      "docTitle": "Order Platform incident runbook",
      "docPath": "ops/order-platform-runbook.md",
      "chunkId": "01KY10BBBBBBBBBBBBBBBBBBBB",
      "snippet": "When orders remain in STUCK status for more than 24 hours, requeue them from the fulfillment console…"
    }
  ],
  "dataCalls": [],
  "entities": [
    { "id": "01KY0ZW3B8AVDR67NXSE96P81N", "name": "Order Platform", "type": "system", "pagerank": 0.0421 }
  ],
  "groundedness": { "verified": 1, "total": 1 },
  "model": { "chat": "claude-sonnet-4-5", "judge": "claude-haiku-4-5" },
  "usage": { "inputTokens": 3980, "outputTokens": 96, "costUsd": 0.0121 },
  "generatedAt": "2026-07-21T09:14:05.001Z"
}

The complete field-by-field schema — including how claims are derived and what groundedness means — is in Structured query (v1).

Which one?

• Reach for /search when you want to control synthesis — a search box, a retrieval-augmented pipeline with your own model, re-ranking, or when you simply need to show a user the source passages. It is cheaper and has no model dependency.
• Reach for /query when you want a finished, defensible answer — a chatbot reply, a report sentence, an alert body — with citations you can click through to prove it. Theclaims array makes every sentence individually auditable.
• Compose them — call /search to preview evidence and /query to commit to an answer, or run /search and hand the chunks to your own agent.

The leverage

The same corpus answers at whatever altitude your product needs — evidence for a human, or a cited conclusion for a machine — from one key and one index. If the consumer is itself an agent, the identical pipeline is a native tool over MCP. Try both endpoints live in the API playground.