Search chunks

POST /api/v1/knowledge-base/search

Run a vector-similarity search against indexed chunks. By default it returns the top matches with no threshold — pass min_similarity to apply a server-side cutoff, or filter/rerank yourself in app code.

Search isn't the call-time path

Agents retrieve from the KB through the query tool type during a call. This endpoint is for outside-of-call usage — building admin dashboards, evals, debug tooling.

Request body

Field	Type	Required	Notes
`query`	string	✓	Natural-language query. Embedded via OpenAI `text-embedding-3-small`.
`limit`	int (1..50)	—	Max results. Defaults to `5`.
`document_uuids`	array of string	—	Limit search to specific document UUIDs. Omit to search every active document in the org.
`min_similarity`	float (0..1)	—	Server-side cutoff — chunks below this cosine similarity are dropped. Omit for no threshold.

Response

{
  "chunks": [
    {
      "id": 4821,
      "document_id": 42,
      "document_uuid": "abc12345-...",
      "filename": "product-faq.pdf",
      "chunk_index": 7,
      "chunk_text": "Refunds are available within 30 days of purchase...",
      "contextualized_text": "In the Returns section: Refunds are available within 30 days...",
      "chunk_metadata": { "page": 3, "section": "Returns" },
      "similarity": 0.847
    }
  ],
  "query": "what is the refund policy",
  "total_results": 1
}

Field	Notes
`chunks[].id` / `document_id`	Numeric chunk id and its parent document's numeric id.
`chunks[].document_uuid`	The parent document's public UUID.
`chunks[].chunk_text`	The chunk text. For `retrieval_mode="full_document"` documents, the whole document is one "chunk".
`chunks[].contextualized_text`	Contextualized variant used for embedding (may be `null`).
`chunks[].chunk_metadata`	Pass-through metadata from Docling (page numbers, headings).
`chunks[].similarity`	Cosine similarity (0..1).
`query`	Echo of the request query.
`total_results`	Number of chunks returned (after any `min_similarity` filter).

Examples

curl -X POST https://dashboard.zoxa.ai/api/v1/knowledge-base/search \
  -H "X-API-Key: zsk_..." \
  -H "Content-Type: application/json" \
  -d '{ "query": "what is the refund policy", "limit": 5, "min_similarity": 0.3 }'

Errors

Status	`detail`	When
`500`	server error	Embedding service or DB error.

Tool types — query — the call-time equivalent

Request body

Response

Examples

Errors

Related

On this page