# Knowledge bases

> List the knowledge bases your agents answer from, search one exactly as the agent does, manage its answers, and read or rewrite its files from your tools.

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

A knowledge base is what an agent looks things up in before it replies: your website, your files and your answers. The API reads every base, searches it the way the agent does, manages its answers, and reads and rewrites its text files.

## Endpoints

| Method | Path | 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` |

An agent answers from one base at a time. `GET /campaigns` gives it as `knowledge_base_id` on each campaign.

## List bases and their sources

`GET /knowledge-bases` lists the bases of the workspace. `GET /knowledge-bases/{id}` adds the detail of one base: each website, each file and the count of answers.

**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": "pricing-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": "opening-hours.txt", "status": "ready", "created_at": "2026-10-09T08:40:10.000+00:00", "pages": null, "size_bytes": 74, "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
  }
}
```

| Field | Meaning |
|---|---|
| `campaign_ids` | The agents that answer from this base: the `id` of `GET /campaigns`. |
| `sources[].kind` | `website`, `file` or `answers`. All the answers of a base read as one source. |
| `sources[].status` | `ready` (the agent can use it), `reading` (being read), `failed` (could not be read) or `empty` (nothing readable in it). |
| `answers_limit` | How many answers the base can hold on your plan. |
| `sources[].editable` | Files only. `true` for a text file (`.txt`, `.md`): its text can be rewritten through the API. `false` for a PDF or a Word file, which the API reads and removes. |
| `can_add_answers` | `false` on a plan that reads its knowledge but adds none. |
| `files_limit`, `can_add_files` | The same for files: how many the base can hold on your plan, and whether your plan adds any. |

In the list, `sources` is a count per kind: `{ "websites": 1, "files": 2, "answers": 14 }`. The list has no cursor.

## Search as the agent does

The search returns the passages the agent is handed when a lead writes a message. It is the same search as at reply time, with the same limits: 4 passages at most, only those close enough to the message, and only the last 500 characters of the message count.

**cURL**

```bash
curl -G "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/search" \
  --data-urlencode "query=how much is the trial session?" \
  -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', 'how much is the trial session?');
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": "how much is the trial session?"},
    headers={"Authorization": "Bearer ws_live_…"},
)
data = r.json()["data"]
```

```json
{
  "data": {
    "query": "how much is the trial session?",
    "matched": true,
    "reason": null,
    "results": [
      { "text": "Q: How much is the trial session?\nA: The trial session is free, with no commitment.", "source": "Q&A", "score": 0.812 },
      { "text": "Memberships start at 39 EUR per month. The first session is offered to every new member.", "source": "pricing-2026.pdf", "score": 0.547 }
    ]
  }
}
```

| Field | Meaning |
|---|---|
| `query` | The text that was searched: the last 500 characters of what you sent. |
| `matched` | `false` when the agent gets nothing from the base for this message. It then answers from its prompt alone. |
| `reason` | Why nothing matched: `no_match` (nothing close enough), `empty` (the base holds nothing yet) or `inactive`. `null` when something matched. |
| `results[].source` | Where the passage comes from: a file name, a page, or `Q&A` for one of your answers. |
| `results[].score` | Closeness to the message, from 0 to 1. Best first. |

Use it for two things: to see what an agent was given when it wrote a reply, and to check that an answer you just added is found. Only replies search the base. The first message and the follow-ups do not.

## Manage answers

An answer is a question and its answer, the same as **Your answers** in the dashboard. It is the most precise thing an agent can know: when a lead asks the question, the agent is handed the answer.

**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": "How much is the trial session?",
    "answer": "The trial session is free, with no commitment."
  }'
```

**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: 'How much is the trial session?',
      answer: 'The trial session is free, with no commitment.',
    }),
  },
);
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": "How much is the trial session?",
        "answer": "The trial session is free, with no commitment.",
    },
)
answer = r.json()["data"]
```

```json
{
  "data": {
    "id": "68e3a90f0026d1e4b7a2",
    "question": "How much is the trial session?",
    "answer": "The trial session is free, with no commitment.",
    "created_at": "2026-10-08T14:20:05.000+00:00",
    "updated_at": "2026-10-08T14:20:05.000+00:00"
  }
}
```

| Call | What it does |
|---|---|
| `GET /knowledge-bases/{id}/answers` | Lists the answers, newest first, with a cursor. |
| `POST /knowledge-bases/{id}/answers` | Adds an answer. Answers `201`. |
| `PATCH /knowledge-bases/{id}/answers/{answerId}` | Changes `question`, `answer`, or both. The previous text is not kept. |
| `DELETE /knowledge-bases/{id}/answers/{answerId}` | Removes the answer. Answers `204`, then `404` if you call it again. |

`question` holds 1 to 1000 characters and `answer` 1 to 4000. A longer text is refused, never cut. The agents that answer from the base use the change on their next reply.

## Read and rewrite a file

`GET /knowledge-bases/{id}` lists the files of a base. Each one has an `id`, and `editable` says whether its text can be rewritten through the API: `true` for a text file (`.txt`, `.md`), `false` for a PDF or a Word file.

### Read a file whole

`GET /knowledge-bases/{id}/files/{fileId}` returns the file with its whole text.

**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": "opening-hours.txt",
    "status": "ready",
    "size_bytes": 74,
    "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": "Monday to Friday: 7 am to 10 pm.\nSaturday: 9 am to 6 pm.\nClosed on Sunday.",
    "text_source": "file",
    "revision": "5f2a9c81d04be637",
    "characters": 74,
    "offset": 0,
    "next_offset": null
  }
}
```

| Field | Meaning |
|---|---|
| `text` | The text of the file. |
| `text_source` | Where the text comes from. `file`: the stored text, to the character (a `.txt`, `.md` or `.csv` file). `passages`: put back together from the passages the agent holds (a PDF or a Word file: its words, without its layout, and not to the character, since a word that ends one passage and starts the next can come back twice or once). `passages_unordered`: the same, when the order of the passages is not known. |
| `revision` | The revision of the whole text, when `text_source` is `file`. Pass it back as `if_revision` when you rewrite the file. `null` for a text put back together from passages, and in the rare case where a change was cut short and the saved text cannot be told (send the whole text then, without `if_revision`). |
| `characters` | The length of the whole text. |
| `next_offset` | `null` when the text is complete. Otherwise call again with `offset` set to this value: a long text comes in windows of `limit` characters (100000 by default, 200000 at most). |
| `passages` | How many passages the agent holds for this file: what the search picks from. |

### Change one place in a text file

`PATCH /knowledge-bases/{id}/files/{fileId}` with `edits` replaces one text by another inside the file. Each `find` must sit exactly once in the file. If one is missing, or sits several times, the call answers `422` and nothing is changed. This is the safe way to change a price or an opening hour without touching the rest.

**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": "Saturday: 9 am to 6 pm.",
        "replace": "Saturday: 9 am to 8 pm."
      }
    ]
  }'
```

**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: "Saturday: 9 am to 6 pm.", replace: "Saturday: 9 am to 8 pm." }],
    }),
  },
);
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": "Saturday: 9 am to 6 pm.", "replace": "Saturday: 9 am to 8 pm."}]},
)
file = r.json()["data"]
```

```json
{
  "data": {
    "id": "68e61c2a0019f0a4d3b1",
    "name": "opening-hours.txt",
    "status": "ready",
    "size_bytes": 74,
    "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": 74,
    "previous_characters": 74
  }
}
```

To replace the whole text, send `text` instead of `edits`. The file keeps its `id` and its name. The agents use the new text on their next reply, and never find the file empty in between. The previous text is not kept: read the file first if you may want it back. Sending the text the file already holds answers `changed: false`.

Send one change at a time for a given file:

- Add `"if_revision"` with the `revision` you read. If the file is no longer that text, the call answers `409` and nothing is changed: read it again, then retry.
- Put several replacements in one `edits` list, not in several calls. Two changes of the same file sent at the same moment are never both saved: one of them, or both, answer `409` and save nothing.
- A change sent while another one is being saved answers `409` too: wait for the other to answer, read the file again, then retry.
- A `502` says in its message what the file holds: either nothing was changed, or the change may be partly applied. In the second case the file is between two texts: for a minute and a half every change of it answers `409`. After that, read it again: it returns the text that was saved. If your change is not in it, send it again.

### Add or remove a file

| Call | What it does |
|---|---|
| `POST /knowledge-bases/{id}/files` | Adds a text file from a `name` and a `text`. It is read at once: when the call answers `201`, the agents can use it. |
| `PATCH /knowledge-bases/{id}/files/{fileId}` | Rewrites a text file, with `edits` or with `text`. |
| `DELETE /knowledge-bases/{id}/files/{fileId}` | Removes a file of any kind, with what the agents learned from it. Answers `204`. It cannot be brought back. |

A `name` ends in `.txt` or `.md`; without an extension it gets `.txt`. A base cannot hold two files of the same name: the call answers `409` and names the file to rewrite. A text written through the API is cut into passages exactly like a file uploaded from the dashboard.

A PDF or a Word file cannot be rewritten in place (`409`). The text the API reads back from it is close to the file, not the file to the character: replacing a PDF by that text is a choice to make after reading it, not a step to automate. A file that is still being read (`status` other than `ready`) can be neither rewritten nor removed yet (`409`).

## What stays in the dashboard

Some things need a crawl, an upload or a choice you make once. They are done in the dashboard, under **Knowledge**:

- creating a base and linking it to an agent,
- adding a website and reading it again,
- uploading a PDF or a Word file,
- deleting a base.

## Limits

| Limit | Value |
|---|---|
| Answers per base | 200 |
| `question` | 1000 characters |
| `answer` | 4000 characters |
| Files per base | 3, 5 or 10 depending on your plan (`files_limit`) |
| Text of a file written through the API | 200000 characters |
| File name | 120 characters |
| `edits` per call | 50 |
| Passages returned by a search | 4 |
| Message length that counts in a search | the last 500 characters |

Adding an answer or a file needs a paid plan. On the free plan you can still read, search, correct and remove what the base already holds.

## Errors you will meet

| HTTP | `code` | When |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Key absent, unknown or revoked. |
| 402 | `plan_limit_reached` | Adding an answer or a file on a plan that adds no knowledge, or to a base that already holds its 200 answers or all the files its plan allows. |
| 403 | `insufficient_scope` | The key lacks `knowledge:read` or `knowledge:write`. A key created before these scopes existed does not have them. |
| 404 | `not_found` | Unknown base, answer or file, or one of another workspace. |
| 409 | `invalid_state` | Rewriting a file that is not a text file, rewriting or removing a file that is still being read, adding a file whose name the base already holds, an `if_revision` that is no longer the file, another change of the same file being saved, or a file whose saved text cannot be told after a change that was cut short. Nothing was changed. |
| 422 | `validation_error` | `query` missing or over 2000 characters, an empty or too long `question`, `answer` or `text`, a `PATCH` with nothing to change, a file name that is not `.txt` or `.md`, an edit whose `find` is not in the file exactly once. |
| 429 | `rate_limited` | Too many requests this minute. Honor `Retry-After`. |
| 502 | `upstream_error` | A store did not answer. The message says what happened: nothing was changed, or the request may be partly applied, and what to do then. Read the base or the file again before retrying. |

## Related

- [Agent prompts](/developers/guides/prompts/)
- [Knowledge bases in the dashboard](/dashboard/knowledge-base/)
- [Campaigns](/developers/guides/campaigns/)
- [MCP server](/developers/mcp/)
