Ir al contenido

Bases de conocimiento

Las bases de conocimiento de tu cuenta: nombre, tipo y origen de cada una, y cómo crear, cambiar y eliminar bases de conocimiento de texto.

Las bases de conocimiento son el contenido del que tus agentes responden preguntas: una web, un texto, un archivo o una integración. Estos endpoints devuelven sus referencias (nombre, tipo, origen y fechas), no el contenido, y te permiten crear, cambiar y eliminar bases de conocimiento de texto. Para leer hace falta knowledge_bases:read; para escribir, knowledge_bases:write.

Endpoint Ruta Permiso
Listar bases de conocimiento GET /v1/knowledge-bases knowledge_bases:read
Una base de conocimiento GET /v1/knowledge-bases/{knowledge_base_id} knowledge_bases:read
Crear una base de conocimiento de texto POST /v1/knowledge-bases knowledge_bases:write
Cambiar una base de conocimiento de texto PATCH /v1/knowledge-bases/{knowledge_base_id} knowledge_bases:write
Eliminar una base de conocimiento de texto DELETE /v1/knowledge-bases/{knowledge_base_id} knowledge_bases:write

GET /v1/knowledge-bases devuelve las bases de conocimiento de tu cuenta, paginadas.

Parámetro Tipo Por defecto Reglas
limit de 1 a 100 50 Elementos por página
cursor texto ninguno meta.next_cursor de la página anterior, con el mismo limit
customer_id UUID el cliente de la clave Consulta qué lee cada clave
Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/knowledge-bases"
{
"data": [
{
"id": "…",
"name": "Preguntas frecuentes",
"type": "WEBSITE",
"source": "https://www.ejemplo.com/faq",
"created_at": "2026-09-01T09:12:00Z",
"updated_at": "2026-10-20T16:40:00Z"
}
],
"meta": { "limit": 50, "next_cursor": null }
}
Campo Qué es
id Identificador de la base de conocimiento
name Nombre en el portal
type WEBSITE, TEXT, FILE o INTEGRATION
source La web o el nombre del archivo del que viene el contenido; null si no aplica
created_at, updated_at Cuándo se creó y se actualizó por última vez (UTC)

GET /v1/knowledge-bases/{knowledge_base_id} devuelve los mismos campos, con una cabecera ETag: la versión que tienes que enviar como If-Match al cambiarla o eliminarla. Una base de conocimiento que no es de tu cliente es 404 not_found.

POST /v1/knowledge-bases crea una base de conocimiento TEXT a partir del texto que envías. Necesita una cabecera Idempotency-Key (consulta Escribir datos) y una clave de todo el cliente: una clave limitada a algunos locales recibe 403 insufficient_scope. Las bases de conocimiento de web y de archivo se crean en el portal.

Campo Reglas
name Obligatorio, de 1 a 200 caracteres: el nombre que muestra el portal
text Obligatorio, de 1 a 200.000 caracteres de texto plano: de lo que responden los agentes
Ventana de terminal
curl -s -X POST "$BASE/knowledge-bases" \
-H "apikey: $BOOKLINE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name": "Horario", "text": "Abrimos todos los días de 13:00 a 16:00 y de 20:00 a 23:30."}'

La respuesta es 201 con la base de conocimiento y su ETag. Tus agentes la usan cuando la vinculas a un local en el portal.

PATCH /v1/knowledge-bases/{knowledge_base_id} cambia name, text o los dos, con las mismas reglas. Envía al menos uno ({} da 422 validation_failed) y el ETag de la base de conocimiento como If-Match.

  • text sustituye todo el contenido. No se añade al final: envía el texto completo cada vez.
  • Solo bases de conocimiento TEXT. Una WEBSITE, FILE o INTEGRATION da 409 conflict: cámbiala en el portal.
  • Si un cambio de texto responde con un 5xx, vuelve a enviar el mismo texto: puede que no haya llegado a tus agentes.
Ventana de terminal
curl -s -X PATCH "$BASE/knowledge-bases/<knowledge_base_id>" \
-H "apikey: $BOOKLINE_API_KEY" \
-H "Content-Type: application/json" \
-H 'If-Match: "<etag>"' \
-d '{"text": "Abrimos todos los días de 13:00 a 16:00 y de 20:00 a 00:00."}'

DELETE /v1/knowledge-bases/{knowledge_base_id} elimina una base de conocimiento TEXT y su contenido. Envía su ETag como If-Match. La respuesta es 204.

  • Una WEBSITE, FILE o INTEGRATION da 409 conflict: elimínala en el portal.
  • Una que todavía usa algún local da 409 conflict: desvincúlala antes de sus locales en el portal. Evita vincularla en el portal mientras la eliminas: la comprobación se hace justo antes de eliminarla, y un local vinculado en ese mismo momento apuntaría a una base de conocimiento eliminada.
  • Referencias, no contenido. El texto o el archivo no se devuelven por la API hoy, ni siquiera en las bases de conocimiento de texto que escribes.
  • Claves limitadas a locales. La clave lista solo las bases de conocimiento que usan esos locales.
  • Si se crean bases de conocimiento mientras recorres las páginas, alguna puede repetirse en la siguiente: quédate con una por id.
  • Escribir datos: versiones, reintentos y el límite de escritura.
  • Agentes: los agentes que responden con ellas.