POST/1.0/knowledge-bases/:id/search

The core RAG primitive over REST: retrieve the most relevant chunks from one knowledge base. Required scope: workbench:knowledge_bases:search (scopes reference) — deliberately separate from read, because semantic search spends a small amount of workspace inference credit per query.

Request body

querystringRequired

What to search for. 1–2000 characters.

modestring

semantic (default) — embeds the query and ranks by meaning. Spends credit.
keyword — free case-insensitive substring match.

limitnumber

Max hits, 1–50. Default 10.

Response

{
  "mode": "semantic",
  "query": "refund window",
  "results": [
    {
      "chunkId": "chk_...",
      "chunkIndex": 4,
      "documentId": "doc_...",
      "documentName": "refund-policy.md",
      "content": "Refunds are processed within 5 business days...",
      "score": 0.87
    }
  ],
  "costUsd": 0.00001,
  "tookMs": 42
}

score is cosine similarity (0–1) for semantic mode, match count for keyword mode. costUsd is the query-embedding spend (always 0 for keyword).

1 min read