Skip to content
Dashboard

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.

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.

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.

Terminal window
curl "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10" \
-H "Authorization: Bearer ws_live_…"
{
"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.

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.

Terminal window
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_…"
{
"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.

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.

Terminal window
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."
}'
{
"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.

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.

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

Terminal window
curl "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1" \
-H "Authorization: Bearer ws_live_…"
{
"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.

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.

Terminal window
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."
}
]
}'
{
"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.
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).

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

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.