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.
Endpoints
Sección titulada «Endpoints»| 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.
Listar las bases y sus fuentes
Sección titulada «Listar las bases y sus fuentes»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.
curl "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10" \ -H "Authorization: Bearer ws_live_…"const res = await fetch( 'https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10', { headers: { Authorization: 'Bearer ws_live_…' } },);const { data: base } = await res.json();import requests
r = requests.get( "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10", headers={"Authorization": "Bearer ws_live_…"},)base = r.json()["data"]{ "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.
Buscar como el agente
Sección titulada «Buscar como el agente»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.
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_…"const url = new URL('https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/search');url.searchParams.set('query', '¿cuánto cuesta la sesión de prueba?');const res = await fetch(url, { headers: { Authorization: 'Bearer ws_live_…' } });const { data } = await res.json();import requests
r = requests.get( "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/search", params={"query": "¿cuánto cuesta la sesión de prueba?"}, headers={"Authorization": "Bearer ws_live_…"},)data = r.json()["data"]{ "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.
Gestionar las respuestas
Sección titulada «Gestionar las respuestas»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.
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." }'const res = await fetch( 'https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/answers', { method: 'POST', headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' }, body: JSON.stringify({ question: '¿Cuánto cuesta la sesión de prueba?', answer: 'La sesión de prueba es gratis, sin compromiso.', }), },);const { data: answer } = await res.json();import requests
r = requests.post( "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/answers", headers={"Authorization": "Bearer ws_live_…"}, json={ "question": "¿Cuánto cuesta la sesión de prueba?", "answer": "La sesión de prueba es gratis, sin compromiso.", },)answer = r.json()["data"]{ "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.
Leer y reescribir un archivo
Sección titulada «Leer y reescribir un archivo»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.
Leer un archivo entero
Sección titulada «Leer un archivo entero»GET /knowledge-bases/{id}/files/{fileId} devuelve el archivo con todo su texto.
curl "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1" \ -H "Authorization: Bearer ws_live_…"const res = await fetch( 'https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1', { headers: { Authorization: 'Bearer ws_live_…' } },);const { data: file } = await res.json();import requests
r = requests.get( "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1", headers={"Authorization": "Bearer ws_live_…"},)file = r.json()["data"]{ "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.
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." } ] }'const res = await fetch( 'https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1', { method: 'PATCH', headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' }, body: JSON.stringify({ edits: [{ find: "Sábado: de 9 h a 18 h.", replace: "Sábado: de 9 h a 20 h." }], }), },);const { data: file } = await res.json();import requests
r = requests.patch( "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1", headers={"Authorization": "Bearer ws_live_…"}, json={"edits": [{"find": "Sábado: de 9 h a 18 h.", "replace": "Sábado: de 9 h a 20 h."}]},)file = r.json()["data"]{ "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 larevisionque leíste. Si el archivo ya no es ese texto, la llamada responde409y 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, responden409y no guardan nada. - Un cambio enviado mientras otro se está guardando responde
409también: espera la respuesta del otro, lee el archivo de nuevo y reintenta. - Un
502dice 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 responde409. Después, léelo de nuevo: devuelve el texto que se guardó. Si tu cambio no está, envíalo otra vez.
Añadir o quitar un archivo
Sección titulada «Añadir o quitar un archivo»| 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).
Lo que se queda en el dashboard
Sección titulada «Lo que se queda en el dashboard»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ímites
Sección titulada «Límites»| 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.
Errores que encontrarás
Sección titulada «Errores que encontrarás»| 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. |