Guides by resource
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.
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
Section titled “Endpoints”| Method | Path | 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 |
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
Section titled “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 "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": "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
Section titled “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 -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_…"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();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"]{ "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
Section titled “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 -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." }'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();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"]{ "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
Section titled “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
Section titled “Read a file whole”GET /knowledge-bases/{id}/files/{fileId} returns the file with its whole text.
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": "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
Section titled “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 -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." } ] }'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();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"]{ "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 therevisionyou read. If the file is no longer that text, the call answers409and nothing is changed: read it again, then retry. - Put several replacements in one
editslist, not in several calls. Two changes of the same file sent at the same moment are never both saved: one of them, or both, answer409and save nothing. - A change sent while another one is being saved answers
409too: wait for the other to answer, read the file again, then retry. - A
502says 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 answers409. 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
Section titled “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
Section titled “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
Section titled “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
Section titled “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. |