Search a Knowledge Base

POST /api/v1/knowledge-bases/:knowledgeBaseId/search — the most relevant chunks for a query.

Returns the chunks that best match a query, using the Knowledge Base's own search mode (hybrid, vector or keyword). This is the same search an Agent with the Knowledge Base attached runs.

POST /api/v1/knowledge-bases/{knowledgeBaseId}/search

Request body

Field	Type	Required	Description
`query`	string	Yes	What to look for.
`maxResults`	integer 1–20	No	Default `5`.
`filters`	object	No	Metadata equality filters, for example `{ "product": "X200" }`. Every key must match.

Response

200 OK

{
  "query": "how do I reset the pump",
  "results": [
    {
      "content": "To reset the X200, hold RESET for five seconds…",
      "score": 0.91,
      "documentId": "9d0a…",
      "documentName": "pump-x200.pdf",
      "chunkIndex": 3,
      "metadata": { "product": "X200" }
    }
  ]
}

Errors

Status	`error`	When
`400`	validation error	`query` is empty or `maxResults` is outside 1–20.
`403`	`forbidden`	Your key is scoped to a different project.
`404`	`not_found`	No such Knowledge Base in your organization.
`409`	`knowledge_base_not_ready`	The Knowledge Base is not `ACTIVE`, for example while it re-indexes. The response carries its `status`.

Example

curl -X POST https://api.elizon.ai/api/v1/knowledge-bases/4f1c…/search \
  -H "X-API-Key: elz_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "query": "how do I reset the pump", "maxResults": 3 }'

Search a Knowledge Base

Request body

Response

Errors

Example

On this page