Skip to main content
POST
Buscar en la base de conocimientos por full-text, vector o híbrido.
Runs a query over the indexed chunks of the knowledge base. Supports three search modes — pick the one that best fits the user’s query: Results are grouped by node_id (the same document appears only once even if several chunks match) and sorted by descending score.

Endpoint

Required scope

knowledge:query

Headers

Body

Example request

Response

200 OK

400 / 401 / 403 / 429

  • 400 BAD_REQUEST: query empty, mode not supported, or node_ids with invalid format.
  • 403 FORBIDDEN with code: INSUFFICIENT_SCOPE: the PAT doesn’t have knowledge:query.
If you’re going to feed the results to an external LLM (RAG), prefer hybrid with top_k=5 as a starting point. It’s the setup that best balances recall (vector) with precision on exact terms (full-text).

Authorizations

Authorization
string
header
required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Body

application/json
query
string
required

Texto de búsqueda.

Example:

"¿cómo cancelar suscripción?"

mode
enum<string>
required

Modo de búsqueda: full (full-text), vector (semántica) o hybrid (combinación con re-ranking).

Available options:
full,
hybrid,
vector
Example:

"hybrid"

top_k
number
default:5

Cantidad máxima de resultados (1-25).

Example:

5

node_ids
string[]

Limita la búsqueda a estos node ids (carpetas o documentos).

Response

200 - application/json
mode
enum<string>
required
Available options:
full,
hybrid,
vector
results
object[]
required