# Bases de connaissances

> Lister les bases de connaissances de tes agents, chercher dans l'une exactement comme l'agent, gérer ses réponses, et lire ou réécrire ses fichiers.

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

Une base de connaissances est ce dans quoi un agent cherche avant de répondre : ton site, tes fichiers et tes réponses. L'API lit chaque base, y cherche comme le fait l'agent, gère ses réponses, et lit et réécrit ses fichiers texte.

## Endpoints

| Méthode | Chemin | 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 agent répond à partir d'une seule base à la fois. `GET /campaigns` la donne dans `knowledge_base_id`, sur chaque campagne.

## Lister les bases et leurs sources

`GET /knowledge-bases` liste les bases de l'espace. `GET /knowledge-bases/{id}` ajoute le détail d'une base : chaque site, chaque fichier et le nombre de réponses.

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

| Champ | Signification |
|---|---|
| `campaign_ids` | Les agents qui répondent à partir de cette base : l'`id` de `GET /campaigns`. |
| `sources[].kind` | `website`, `file` ou `answers`. Toutes les réponses d'une base se lisent comme une seule source. |
| `sources[].status` | `ready` (l'agent peut s'en servir), `reading` (lecture en cours), `failed` (n'a pas pu être lue) ou `empty` (rien de lisible dedans). |
| `answers_limit` | Le nombre de réponses que la base peut contenir avec ton forfait. |
| `sources[].editable` | Fichiers seulement. `true` pour un fichier texte (`.txt`, `.md`) : son texte peut être réécrit par l'API. `false` pour un PDF ou un fichier Word, que l'API lit et retire. |
| `can_add_answers` | `false` sur un forfait qui lit ses connaissances mais n'en ajoute pas. |
| `files_limit`, `can_add_files` | La même chose pour les fichiers : combien la base peut en contenir avec ton forfait, et si ton forfait en ajoute. |

Dans la liste, `sources` est un compte par type : `{ "websites": 1, "files": 2, "answers": 14 }`. La liste n'a pas de curseur.

## Chercher comme l'agent

La recherche renvoie les passages que l'agent reçoit quand un prospect écrit un message. C'est la même recherche qu'au moment de répondre, avec les mêmes limites : 4 passages au plus, seulement ceux qui sont assez proches du message, et seuls les 500 derniers caractères du message comptent.

**cURL**

```bash
curl -G "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/search" \
  --data-urlencode "query=c'est combien la séance d'essai ?" \
  -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', "c'est combien la séance d'essai ?");
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": "c'est combien la séance d'essai ?"},
    headers={"Authorization": "Bearer ws_live_…"},
)
data = r.json()["data"]
```

```json
{
  "data": {
    "query": "c'est combien la séance d'essai ?",
    "matched": true,
    "reason": null,
    "results": [
      { "text": "Q: Combien coûte la séance d'essai ?\nA: La séance d'essai est offerte, sans engagement.", "source": "Q&A", "score": 0.812 },
      { "text": "Les abonnements commencent à 39 EUR par mois. La première séance est offerte à chaque nouveau membre.", "source": "tarifs-2026.pdf", "score": 0.547 }
    ]
  }
}
```

| Champ | Signification |
|---|---|
| `query` | Le texte qui a été cherché : les 500 derniers caractères de ce que tu as envoyé. |
| `matched` | `false` quand l'agent ne reçoit rien de la base pour ce message. Il répond alors avec son prompt seul. |
| `reason` | Pourquoi rien n'a été trouvé : `no_match` (rien d'assez proche), `empty` (la base ne contient encore rien) ou `inactive`. `null` quand un passage a été trouvé. |
| `results[].source` | D'où vient le passage : un nom de fichier, une page, ou `Q&A` pour l'une de tes réponses. |
| `results[].score` | La proximité avec le message, de 0 à 1. Le meilleur en premier. |

Elle sert à deux choses : voir ce qu'un agent a reçu quand il a écrit une réponse, et vérifier qu'une réponse que tu viens d'ajouter est bien trouvée. Seules les réponses cherchent dans la base. Le premier message et les relances ne le font pas.

## Gérer les réponses

Une réponse est une question et sa réponse, la même chose que **Tes réponses** dans le dashboard. C'est ce qu'un agent peut savoir de plus précis : quand un prospect pose la question, l'agent reçoit la réponse.

**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": "Combien coûte la séance d’essai ?",
    "answer": "La séance d’essai est offerte, sans engagement."
  }'
```

**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: 'Combien coûte la séance d’essai ?',
      answer: 'La séance d’essai est offerte, sans engagement.',
    }),
  },
);
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": "Combien coûte la séance d’essai ?",
        "answer": "La séance d’essai est offerte, sans engagement.",
    },
)
answer = r.json()["data"]
```

```json
{
  "data": {
    "id": "68e3a90f0026d1e4b7a2",
    "question": "Combien coûte la séance d’essai ?",
    "answer": "La séance d’essai est offerte, sans engagement.",
    "created_at": "2026-10-08T14:20:05.000+00:00",
    "updated_at": "2026-10-08T14:20:05.000+00:00"
  }
}
```

| Appel | Ce qu'il fait |
|---|---|
| `GET /knowledge-bases/{id}/answers` | Liste les réponses, de la plus récente à la plus ancienne, avec un curseur. |
| `POST /knowledge-bases/{id}/answers` | Ajoute une réponse. Répond `201`. |
| `PATCH /knowledge-bases/{id}/answers/{answerId}` | Change `question`, `answer`, ou les deux. Le texte précédent n'est pas gardé. |
| `DELETE /knowledge-bases/{id}/answers/{answerId}` | Retire la réponse. Répond `204`, puis `404` si tu l'appelles de nouveau. |

`question` contient de 1 à 1000 caractères et `answer` de 1 à 4000. Un texte plus long est refusé, jamais coupé. Les agents qui répondent à partir de la base utilisent le changement dès leur prochaine réponse.

## Lire et réécrire un fichier

`GET /knowledge-bases/{id}` liste les fichiers d'une base. Chacun a un `id`, et `editable` dit si son texte peut être réécrit par l'API : `true` pour un fichier texte (`.txt`, `.md`), `false` pour un PDF ou un fichier Word.

### Lire un fichier en entier

`GET /knowledge-bases/{id}/files/{fileId}` renvoie le fichier avec tout son texte.

**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": "horaires.txt",
    "status": "ready",
    "size_bytes": 77,
    "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": "Du lundi au vendredi : 7 h à 22 h.\nSamedi : 9 h à 18 h.\nFermé le dimanche.",
    "text_source": "file",
    "revision": "5f2a9c81d04be637",
    "characters": 74,
    "offset": 0,
    "next_offset": null
  }
}
```

| Champ | Signification |
|---|---|
| `text` | Le texte du fichier. |
| `text_source` | D'où vient le texte. `file` : le texte enregistré, au caractère près (un fichier `.txt`, `.md` ou `.csv`). `passages` : reconstitué à partir des passages que l'agent détient (un PDF ou un fichier Word : ses mots, sans sa mise en page, et pas au caractère près, car un mot qui finit un passage et commence le suivant peut revenir deux fois ou une seule). `passages_unordered` : la même chose, quand l'ordre des passages n'est pas connu. |
| `revision` | La révision du texte entier, quand `text_source` vaut `file`. Renvoie-la dans `if_revision` quand tu réécris le fichier. `null` pour un texte reconstitué à partir de passages, et dans le cas rare où une modification a été interrompue sans qu'on puisse dire quel texte a été enregistré (envoie alors le texte entier, sans `if_revision`). |
| `characters` | La longueur du texte entier. |
| `next_offset` | `null` quand le texte est complet. Sinon, rappelle avec `offset` à cette valeur : un long texte arrive par fenêtres de `limit` caractères (100000 par défaut, 200000 au plus). |
| `passages` | Le nombre de passages que l'agent détient pour ce fichier : ce dans quoi la recherche choisit. |

### Changer un seul endroit dans un fichier texte

`PATCH /knowledge-bases/{id}/files/{fileId}` avec `edits` remplace un texte par un autre à l'intérieur du fichier. Chaque `find` doit se trouver exactement une fois dans le fichier. S'il manque, ou s'il s'y trouve plusieurs fois, l'appel répond `422` et rien n'est changé. C'est la façon sûre de changer un prix ou un horaire sans toucher au reste.

**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": "Samedi : 9 h à 18 h.",
        "replace": "Samedi : 9 h à 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: "Samedi : 9 h à 18 h.", replace: "Samedi : 9 h à 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": "Samedi : 9 h à 18 h.", "replace": "Samedi : 9 h à 20 h."}]},
)
file = r.json()["data"]
```

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

Pour remplacer tout le texte, envoie `text` à la place de `edits`. Le fichier garde son `id` et son nom. Les agents utilisent le nouveau texte dès leur prochaine réponse, et ne trouvent jamais le fichier vide entre les deux. Le texte précédent n'est pas gardé : lis le fichier avant si tu peux vouloir le retrouver. Envoyer le texte que le fichier contient déjà répond `changed: false`.

Envoie une seule modification à la fois pour un fichier donné :

- Ajoute `"if_revision"` avec la `revision` que tu as lue. Si le fichier n'est plus ce texte, l'appel répond `409` et rien n'est modifié : relis-le, puis réessaie.
- Mets plusieurs remplacements dans une seule liste `edits`, pas dans plusieurs appels. Deux modifications du même fichier envoyées au même instant ne sont jamais enregistrées toutes les deux : l'une d'elles, ou les deux, répondent `409` et n'enregistrent rien.
- Une modification envoyée pendant qu'une autre est en cours d'enregistrement répond `409` aussi : attends la réponse de l'autre, relis le fichier, puis réessaie.
- Un `502` dit dans son message ce que le fichier contient : soit rien n'a été modifié, soit la modification est peut-être appliquée en partie. Dans le second cas le fichier est entre deux textes : pendant une minute et demie toute modification répond `409`. Ensuite, relis-le : il renvoie le texte qui a été enregistré. Si ta modification n'y est pas, renvoie-la.

### Ajouter ou retirer un fichier

| Appel | Ce qu'il fait |
|---|---|
| `POST /knowledge-bases/{id}/files` | Ajoute un fichier texte à partir d'un `name` et d'un `text`. Il est lu tout de suite : quand l'appel répond `201`, les agents peuvent s'en servir. |
| `PATCH /knowledge-bases/{id}/files/{fileId}` | Réécrit un fichier texte, avec `edits` ou avec `text`. |
| `DELETE /knowledge-bases/{id}/files/{fileId}` | Retire un fichier, quel que soit son type, avec ce que les agents en ont appris. Répond `204`. Il ne peut pas être récupéré. |

Un `name` se termine par `.txt` ou `.md` ; sans extension, il reçoit `.txt`. Une base ne peut pas contenir deux fichiers du même nom : l'appel répond `409` et nomme le fichier à réécrire. Un texte écrit par l'API est découpé en passages exactement comme un fichier envoyé depuis le dashboard.

Un PDF ou un fichier Word ne peut pas être réécrit sur place (`409`). Le texte que l'API en relit est proche du fichier, pas le fichier au caractère près : remplacer un PDF par ce texte est un choix à faire après l'avoir lu, pas une étape à automatiser. Un fichier encore en cours de lecture (`status` autre que `ready`) ne peut être ni réécrit ni retiré pour l'instant (`409`).

## Ce qui reste dans le dashboard

Certaines choses demandent une lecture de site, un envoi de fichier ou un choix fait une fois. Elles se font dans le dashboard, dans **Connaissances** :

- créer une base et la relier à un agent,
- ajouter un site et le relire,
- envoyer un PDF ou un fichier Word,
- supprimer une base.

## Limites

| Limite | Valeur |
|---|---|
| Réponses par base | 200 |
| `question` | 1000 caractères |
| `answer` | 4000 caractères |
| Fichiers par base | 3, 5 ou 10 selon ton forfait (`files_limit`) |
| Texte d'un fichier écrit par l'API | 200000 caractères |
| Nom d'un fichier | 120 caractères |
| `edits` par appel | 50 |
| Passages renvoyés par une recherche | 4 |
| Longueur du message qui compte dans une recherche | les 500 derniers caractères |

Ajouter une réponse ou un fichier demande un forfait payant. Avec l'offre gratuite, tu peux toujours lire, chercher, corriger et retirer ce que la base contient déjà.

## Les erreurs que tu rencontreras

| HTTP | `code` | Quand |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Clé absente, inconnue ou révoquée. |
| 402 | `plan_limit_reached` | Ajout d'une réponse ou d'un fichier avec un forfait qui n'ajoute pas de connaissances, ou dans une base qui contient déjà ses 200 réponses ou tous les fichiers que son forfait permet. |
| 403 | `insufficient_scope` | Il manque `knowledge:read` ou `knowledge:write` à la clé. Une clé créée avant l'existence de ces scopes ne les a pas. |
| 404 | `not_found` | Base, réponse ou fichier inconnu, ou d'un autre espace. |
| 409 | `invalid_state` | Réécriture d'un fichier qui n'est pas un fichier texte, réécriture ou retrait d'un fichier encore en cours de lecture, ajout d'un fichier dont la base contient déjà le nom, `if_revision` qui n'est plus celle du fichier, autre modification du même fichier en cours d'enregistrement, ou fichier dont on ne peut pas dire quel texte a été enregistré après une modification interrompue. Rien n'a été modifié. |
| 422 | `validation_error` | `query` absent ou de plus de 2000 caractères, `question`, `answer` ou `text` vide ou trop long, un `PATCH` sans rien à changer, un nom de fichier qui n'est ni `.txt` ni `.md`, un `find` qui ne se trouve pas exactement une fois dans le fichier. |
| 429 | `rate_limited` | Trop de requêtes cette minute. Respecte `Retry-After`. |
| 502 | `upstream_error` | Un stockage n'a pas répondu. Le message dit ce qui s'est passé : rien n'a été modifié, ou la demande est peut-être appliquée en partie, et quoi faire dans ce cas. Relis la base ou le fichier avant de réessayer. |

## Voir aussi

- [Prompts des agents](/fr/developers/guides/prompts/)
- [Bases de connaissances dans le dashboard](/fr/dashboard/knowledge-base/)
- [Campagnes](/fr/developers/guides/campaigns/)
- [Serveur MCP](/fr/developers/mcp/)
