# 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.

Source: https://docs.whatsetter.com/es/developers/guides/knowledge/

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

| Método | Ruta | Scope |
|---|---|---|
| GET | [`/knowledge-bases`](/api-reference/operations/listknowledgebases/) | `knowledge:read` |
| GET | [`/knowledge-bases/{id}`](/api-reference/operations/getknowledgebase/) | `knowledge:read` |
| GET | [`/knowledge-bases/{id}/search`](/api-reference/operations/searchknowledgebase/) | `knowledge:read` |
| GET | [`/knowledge-bases/{id}/answers`](/api-reference/operations/listknowledgeanswers/) | `knowledge:read` |
| POST | [`/knowledge-bases/{id}/answers`](/api-reference/operations/createknowledgeanswer/) | `knowledge:write` |
| PATCH | [`/knowledge-bases/{id}/answers/{answerId}`](/api-reference/operations/updateknowledgeanswer/) | `knowledge:write` |
| DELETE | [`/knowledge-bases/{id}/answers/{answerId}`](/api-reference/operations/deleteknowledgeanswer/) | `knowledge:write` |
| GET | [`/knowledge-bases/{id}/files/{fileId}`](/api-reference/operations/getknowledgefile/) | `knowledge:read` |
| POST | [`/knowledge-bases/{id}/files`](/api-reference/operations/createknowledgefile/) | `knowledge:write` |
| PATCH | [`/knowledge-bases/{id}/files/{fileId}`](/api-reference/operations/updateknowledgefile/) | `knowledge:write` |
| DELETE | [`/knowledge-bases/{id}/files/{fileId}`](/api-reference/operations/deleteknowledgefile/) | `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

`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**

```bash
curl "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data: base } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10",
    headers={"Authorization": "Bearer ws_live_…"},
)
base = r.json()["data"]
```

```json
{
  "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

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**

```bash
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_…"
```

**JavaScript**

```js
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();
```

**Python**

```python
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"]
```

```json
{
  "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

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**

```bash
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."
  }'
```

**JavaScript**

```js
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();
```

**Python**

```python
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"]
```

```json
{
  "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

`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

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

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
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();
```

**Python**

```python
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"]
```

```json
{
  "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

`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**

```bash
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."
      }
    ]
  }'
```

**JavaScript**

```js
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();
```

**Python**

```python
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"]
```

```json
{
  "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.

### 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

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

| 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

| 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. |

## Relacionado

- [Prompts de los agentes](/es/developers/guides/prompts/)
- [Bases de conocimientos en el dashboard](/es/dashboard/knowledge-base/)
- [Campañas](/es/developers/guides/campaigns/)
- [Servidor MCP](/es/developers/mcp/)
