Ir al contenido
Dashboard

Guías por recurso

Bases de conocimientos

Listar las bases de conocimientos de tus agentes, buscar en una exactamente como el agente, gestionar sus respuestas, y leer o reescribir sus archivos.

Una base de conocimientos es donde un agente busca antes de responder: tu sitio web, tus archivos y tus respuestas. La API lee cada base, busca en ella como lo hace el agente, gestiona sus respuestas, y lee y reescribe sus archivos de texto.

Método Ruta Scope
GET /knowledge-bases knowledge:read
GET /knowledge-bases/{id} knowledge:read
GET /knowledge-bases/{id}/search knowledge:read
GET /knowledge-bases/{id}/answers knowledge:read
POST /knowledge-bases/{id}/answers knowledge:write
PATCH /knowledge-bases/{id}/answers/{answerId} knowledge:write
DELETE /knowledge-bases/{id}/answers/{answerId} knowledge:write
GET /knowledge-bases/{id}/files/{fileId} knowledge:read
POST /knowledge-bases/{id}/files knowledge:write
PATCH /knowledge-bases/{id}/files/{fileId} knowledge:write
DELETE /knowledge-bases/{id}/files/{fileId} knowledge:write

Un agente responde a partir de una sola base a la vez. GET /campaigns la da en knowledge_base_id, en cada campaña.

GET /knowledge-bases lista las bases del espacio. GET /knowledge-bases/{id} añade el detalle de una base: cada sitio, cada archivo y el número de respuestas.

Terminal window
curl "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10" \
-H "Authorization: Bearer ws_live_…"
{
"data": {
"id": "68c1f1c4001a09be5d10",
"name": "Acme France",
"campaign_ids": ["66f1a2b3c4d5e6f7a8b9c0c1"],
"created_at": "2026-09-02T09:19:48.000+00:00",
"sources": [
{ "id": "68c1f1d80033a1b07c55", "kind": "website", "name": "acme.fr", "status": "ready", "created_at": "2026-09-02T09:20:08.000+00:00", "url": "https://acme.fr", "pages_read": 12, "pages_found": 13, "last_read_at": "2026-10-05T03:17:02.000+00:00" },
{ "id": "68d40b7e000f1c2d3a66", "kind": "file", "name": "precios-2026.pdf", "status": "ready", "created_at": "2026-09-24T15:02:54.000+00:00", "pages": 3, "size_bytes": 184220, "editable": false },
{ "id": "68e61c2a0019f0a4d3b1", "kind": "file", "name": "horarios.txt", "status": "ready", "created_at": "2026-10-09T08:40:10.000+00:00", "pages": null, "size_bytes": 78, "editable": true },
{ "id": null, "kind": "answers", "name": null, "status": "ready", "created_at": "2026-09-03T08:11:40.000+00:00", "answers": 14 }
],
"answers_limit": 200,
"can_add_answers": true,
"files_limit": 5,
"can_add_files": true
}
}
Campo Significado
campaign_ids Los agentes que responden a partir de esta base: el id de GET /campaigns.
sources[].kind website, file o answers. Todas las respuestas de una base se leen como una sola fuente.
sources[].status ready (el agente puede usarla), reading (se está leyendo), failed (no se pudo leer) o empty (nada legible dentro).
answers_limit Cuántas respuestas puede contener la base con tu plan.
sources[].editable Solo archivos. true para un archivo de texto (.txt, .md): su texto se puede reescribir con la API. false para un PDF o un archivo Word, que la API lee y quita.
can_add_answers false en un plan que lee sus conocimientos pero no añade ninguno.
files_limit, can_add_files Lo mismo para los archivos: cuántos puede contener la base con tu plan, y si tu plan añade alguno.

En la lista, sources es un recuento por tipo: { "websites": 1, "files": 2, "answers": 14 }. La lista no tiene cursor.

La búsqueda devuelve los pasajes que el agente recibe cuando un lead escribe un mensaje. Es la misma búsqueda que al responder, con los mismos límites: 4 pasajes como máximo, solo los que están lo bastante cerca del mensaje, y solo cuentan los últimos 500 caracteres del mensaje.

Terminal window
curl -G "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/search" \
--data-urlencode "query=¿cuánto cuesta la sesión de prueba?" \
-H "Authorization: Bearer ws_live_…"
{
"data": {
"query": "¿cuánto cuesta la sesión de prueba?",
"matched": true,
"reason": null,
"results": [
{ "text": "Q: ¿Cuánto cuesta la sesión de prueba?\nA: La sesión de prueba es gratis, sin compromiso.", "source": "Q&A", "score": 0.812 },
{ "text": "Las cuotas empiezan en 39 EUR al mes. La primera sesión se ofrece a cada nuevo socio.", "source": "precios-2026.pdf", "score": 0.547 }
]
}
}
Campo Significado
query El texto que se buscó: los últimos 500 caracteres de lo que enviaste.
matched false cuando el agente no recibe nada de la base para este mensaje. Entonces responde solo con su prompt.
reason Por qué no se encontró nada: no_match (nada lo bastante cerca), empty (la base aún no contiene nada) o inactive. null cuando se encontró algo.
results[].source De dónde viene el pasaje: un nombre de archivo, una página, o Q&A para una de tus respuestas.
results[].score La cercanía con el mensaje, de 0 a 1. El mejor primero.

Sirve para dos cosas: ver qué recibió un agente cuando escribió una respuesta, y comprobar que una respuesta que acabas de añadir se encuentra. Solo las respuestas buscan en la base. El primer mensaje y los seguimientos no lo hacen.

Una respuesta es una pregunta y su respuesta, lo mismo que Tus respuestas en el dashboard. Es lo más preciso que un agente puede saber: cuando un lead hace la pregunta, el agente recibe la respuesta.

Terminal window
curl -X POST "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/answers" \
-H "Authorization: Bearer ws_live_…" \
-H "Content-Type: application/json" \
-d '{
"question": "¿Cuánto cuesta la sesión de prueba?",
"answer": "La sesión de prueba es gratis, sin compromiso."
}'
{
"data": {
"id": "68e3a90f0026d1e4b7a2",
"question": "¿Cuánto cuesta la sesión de prueba?",
"answer": "La sesión de prueba es gratis, sin compromiso.",
"created_at": "2026-10-08T14:20:05.000+00:00",
"updated_at": "2026-10-08T14:20:05.000+00:00"
}
}
Llamada Qué hace
GET /knowledge-bases/{id}/answers Lista las respuestas, de la más reciente a la más antigua, con un cursor.
POST /knowledge-bases/{id}/answers Añade una respuesta. Responde 201.
PATCH /knowledge-bases/{id}/answers/{answerId} Cambia question, answer, o ambas. El texto anterior no se guarda.
DELETE /knowledge-bases/{id}/answers/{answerId} Quita la respuesta. Responde 204, y luego 404 si la llamas de nuevo.

question contiene de 1 a 1000 caracteres y answer de 1 a 4000. Un texto más largo se rechaza, nunca se corta. Los agentes que responden a partir de la base usan el cambio desde su próxima respuesta.

GET /knowledge-bases/{id} lista los archivos de una base. Cada uno tiene un id, y editable dice si su texto se puede reescribir con la API: true para un archivo de texto (.txt, .md), false para un PDF o un archivo Word.

GET /knowledge-bases/{id}/files/{fileId} devuelve el archivo con todo su texto.

Terminal window
curl "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1" \
-H "Authorization: Bearer ws_live_…"
{
"data": {
"id": "68e61c2a0019f0a4d3b1",
"name": "horarios.txt",
"status": "ready",
"size_bytes": 78,
"pages": null,
"passages": 1,
"editable": true,
"created_at": "2026-10-09T08:40:10.000+00:00",
"updated_at": "2026-10-09T08:40:10.000+00:00",
"text": "De lunes a viernes: de 7 h a 22 h.\nSábado: de 9 h a 18 h.\nCerrado el domingo.",
"text_source": "file",
"revision": "5f2a9c81d04be637",
"characters": 77,
"offset": 0,
"next_offset": null
}
}
Campo Significado
text El texto del archivo.
text_source De dónde viene el texto. file: el texto guardado, carácter por carácter (un archivo .txt, .md o .csv). passages: reconstruido a partir de los pasajes que el agente tiene (un PDF o un archivo Word: sus palabras, sin su maquetación, y no carácter por carácter, porque una palabra que termina un pasaje y empieza el siguiente puede volver dos veces o una sola). passages_unordered: lo mismo, cuando no se conoce el orden de los pasajes.
revision La revisión del texto entero, cuando text_source vale file. Devuélvela en if_revision cuando reescribas el archivo. null para un texto reconstruido a partir de pasajes, y en el caso raro en que un cambio se interrumpió y no se puede saber qué texto se guardó (envía entonces el texto entero, sin if_revision).
characters La longitud del texto entero.
next_offset null cuando el texto está completo. Si no, vuelve a llamar con offset en ese valor: un texto largo llega por ventanas de limit caracteres (100000 por defecto, 200000 como máximo).
passages Cuántos pasajes tiene el agente de este archivo: de ahí elige la búsqueda.

Cambiar un solo lugar en un archivo de texto

Sección titulada «Cambiar un solo lugar en un archivo de texto»

PATCH /knowledge-bases/{id}/files/{fileId} con edits reemplaza un texto por otro dentro del archivo. Cada find debe estar exactamente una vez en el archivo. Si falta, o está varias veces, la llamada responde 422 y no se cambia nada. Es la forma segura de cambiar un precio o un horario sin tocar el resto.

Terminal window
curl -X PATCH "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1" \
-H "Authorization: Bearer ws_live_…" \
-H "Content-Type: application/json" \
-d '{
"edits": [
{
"find": "Sábado: de 9 h a 18 h.",
"replace": "Sábado: de 9 h a 20 h."
}
]
}'
{
"data": {
"id": "68e61c2a0019f0a4d3b1",
"name": "horarios.txt",
"status": "ready",
"size_bytes": 78,
"pages": null,
"passages": 1,
"editable": true,
"created_at": "2026-10-09T08:40:10.000+00:00",
"updated_at": "2026-10-09T09:02:31.000+00:00",
"changed": true,
"revision": "c41d7e0a92b3f586",
"characters": 77,
"previous_characters": 77
}
}

Para reemplazar todo el texto, envía text en lugar de edits. El archivo conserva su id y su nombre. Los agentes usan el texto nuevo desde su próxima respuesta, y nunca encuentran el archivo vacío entre tanto. El texto anterior no se guarda: lee el archivo antes si puedes querer recuperarlo. Enviar el texto que el archivo ya contiene responde changed: false.

Envía un solo cambio a la vez para un mismo archivo:

  • Añade "if_revision" con la revision que leíste. Si el archivo ya no es ese texto, la llamada responde 409 y no se cambia nada: léelo de nuevo y reintenta.
  • Pon varios reemplazos en una sola lista edits, no en varias llamadas. Dos cambios del mismo archivo enviados en el mismo instante nunca se guardan los dos: uno de ellos, o ambos, responden 409 y no guardan nada.
  • Un cambio enviado mientras otro se está guardando responde 409 también: espera la respuesta del otro, lee el archivo de nuevo y reintenta.
  • Un 502 dice en su mensaje lo que contiene el archivo: o no se cambió nada, o el cambio quizá está aplicado en parte. En el segundo caso el archivo está entre dos textos: durante un minuto y medio todo cambio responde 409. Después, léelo de nuevo: devuelve el texto que se guardó. Si tu cambio no está, envíalo otra vez.
Llamada Qué hace
POST /knowledge-bases/{id}/files Añade un archivo de texto a partir de un name y un text. Se lee enseguida: cuando la llamada responde 201, los agentes pueden usarlo.
PATCH /knowledge-bases/{id}/files/{fileId} Reescribe un archivo de texto, con edits o con text.
DELETE /knowledge-bases/{id}/files/{fileId} Quita un archivo de cualquier tipo, con lo que los agentes aprendieron de él. Responde 204. No se puede recuperar.

Un name termina en .txt o .md; sin extensión, recibe .txt. Una base no puede contener dos archivos con el mismo nombre: la llamada responde 409 y nombra el archivo que hay que reescribir. Un texto escrito con la API se corta en pasajes exactamente como un archivo subido desde el dashboard.

Un PDF o un archivo Word no se puede reescribir en su sitio (409). El texto que la API relee de él se parece al archivo, pero no es el archivo carácter por carácter: reemplazar un PDF por ese texto es una decisión que se toma después de leerlo, no un paso que automatizar. Un archivo que todavía se está leyendo (status distinto de ready) no se puede reescribir ni quitar por ahora (409).

Algunas cosas piden leer un sitio, subir un archivo o una elección que haces una vez. Se hacen en el dashboard, en Conocimientos:

  • crear una base y vincularla a un agente,
  • añadir un sitio y releerlo,
  • subir un PDF o un archivo Word,
  • eliminar una base.
Límite Valor
Respuestas por base 200
question 1000 caracteres
answer 4000 caracteres
Archivos por base 3, 5 o 10 según tu plan (files_limit)
Texto de un archivo escrito con la API 200000 caracteres
Nombre de un archivo 120 caracteres
edits por llamada 50
Pasajes devueltos por una búsqueda 4
Longitud del mensaje que cuenta en una búsqueda los últimos 500 caracteres

Añadir una respuesta o un archivo requiere un plan de pago. Con el plan gratis aún puedes leer, buscar, corregir y quitar lo que la base ya contiene.

HTTP code Cuándo
401 missing_api_key, invalid_api_key Clave ausente, desconocida o revocada.
402 plan_limit_reached Añadir una respuesta o un archivo con un plan que no añade conocimientos, o en una base que ya contiene sus 200 respuestas o todos los archivos que permite su plan.
403 insufficient_scope A la clave le falta knowledge:read o knowledge:write. Una clave creada antes de que existieran estos scopes no los tiene.
404 not_found Base, respuesta o archivo desconocido, o de otro espacio.
409 invalid_state Reescribir un archivo que no es de texto, reescribir o quitar un archivo que todavía se está leyendo, añadir un archivo cuyo nombre ya tiene la base, un if_revision que ya no es el del archivo, otro cambio del mismo archivo que se está guardando, o un archivo del que no se puede saber qué texto se guardó tras un cambio interrumpido. No se cambió nada.
422 validation_error query ausente o de más de 2000 caracteres, question, answer o text vacío o demasiado largo, un PATCH sin nada que cambiar, un nombre de archivo que no es .txt ni .md, un find que no está exactamente una vez en el archivo.
429 rate_limited Demasiadas peticiones este minuto. Respeta Retry-After.
502 upstream_error Un almacén no respondió. El mensaje dice lo que pasó: no se cambió nada, o la petición quizá está aplicada en parte, y qué hacer entonces. Lee de nuevo la base o el archivo antes de reintentar.