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 |
Listar bases de conocimiento
Sección titulada «Listar bases de conocimiento»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 |
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) |
Una base de conocimiento
Sección titulada «Una base de conocimiento»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.
Crear una base de conocimiento de texto
Sección titulada «Crear una base de conocimiento de texto»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 |
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.
Cambiar una base de conocimiento de texto
Sección titulada «Cambiar una base de conocimiento de texto»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.
textsustituye todo el contenido. No se añade al final: envía el texto completo cada vez.- Solo bases de conocimiento
TEXT. UnaWEBSITE,FILEoINTEGRATIONda 409conflict: 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.
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."}'Eliminar una base de conocimiento de texto
Sección titulada «Eliminar una base de conocimiento de texto»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,FILEoINTEGRATIONda 409conflict: 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.
Reglas de los datos
Sección titulada «Reglas de los datos»- 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.
Relacionado
Sección titulada «Relacionado»- Escribir datos: versiones, reintentos y el límite de escritura.
- Agentes: los agentes que responden con ellas.
