Skip to main content
POST
/
v1
/
knowledge
/
search
Buscar en la base de conocimientos por full-text, vector o híbrido.
curl --request POST \
  --url https://api.keebai.com/v1/knowledge/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "¿cómo cancelar suscripción?",
  "mode": "hybrid",
  "top_k": 5,
  "node_ids": [
    "<string>"
  ]
}
'
{
  "results": [
    {
      "node_id": "<string>",
      "score": 123,
      "title": "<string>",
      "snippet": "<string>"
    }
  ]
}
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:
ModeWhen to use itHow it works internally
fullExact terms, keywords, numbers, IDs.MongoDB text index over page_content with Spanish stemming.
vectorNatural language questions, synonyms, paraphrasing.MongoDB Atlas Vector Search with text-embedding-3-small embeddings.
hybridSensible default when you don’t know what kind of query is coming.Runs both in parallel, normalizes scores, and combines them with a 0.6 vector / 0.4 full-text weight.
Results are grouped by node_id (the same document appears only once even if several chunks match) and sorted by descending score.

​
Endpoint

POST https://api.keebai.com/v1/knowledge/search

​
Required scope

knowledge:query

​
Headers

HeaderRequiredValue
AuthorizationYesBearer kbai_pk_<token>
Content-TypeYesapplication/json

​
Body

FieldTypeRequiredDescription
querystringYesSearch text.
modestringYesfull, vector, or hybrid.
top_knumberNoMax number of results, between 1 and 25. Default 5.
node_idsstring[]NoRestrict the search to these node_id values (folders or documents). Useful to scope to a domain within the tree. Max 100 ids.

​
Example request

curl -X POST https://api.keebai.com/v1/knowledge/search \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "¿cómo cancelar mi suscripción?",
    "mode": "hybrid",
    "top_k": 3
  }'

​
Response

​
200 OK

{
  "mode": "hybrid",
  "results": [
    {
      "node_id": "65f3a1b2c3d4e5f6a7b8c9d3",
      "title": "Política de devolución",
      "snippet": "Las devoluciones se aceptan dentro de los 10 días posteriores a la compra...",
      "score": 0.873,
      "source": "vector"
    },
    {
      "node_id": "65f3a1b2c3d4e5f6a7b8c9d4",
      "title": "Cancelación de suscripciones",
      "snippet": "Para cancelar tu suscripción, ingresá a Mi cuenta > Suscripciones...",
      "score": 0.612,
      "source": "full"
    }
  ]
}
FieldTypeDescription
modestringMode applied (same as in the request).
results[].node_idstringObjectId of the document in the knowledge base. Useful for cross-referencing with GET /v1/knowledge/tree.
results[].titlestringDocument title (no full content).
results[].snippetstringFragment of the highest-scoring chunk, truncated to ~320 characters.
results[].scorenumberNormalized score. The scale depends on the mode: in vector and hybrid it’s in [0,1]; in full it’s the raw Mongo textScore. Only comparable between items in the same response.
results[].sourcestringvector or full, depending on which engine produced the top-scoring match (in hybrid it indicates which one won after combination).

​
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