Knowledge
Add a text file
const url = 'https://app.whatsetter.com/api/v1/knowledge-bases/example/files';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"opening-hours.txt","text":"Monday to Friday: 7 am to 10 pm.\nSaturday: 9 am to 6 pm.\nClosed on Sunday."}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://app.whatsetter.com/api/v1/knowledge-bases/example/files \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "opening-hours.txt", "text": "Monday to Friday: 7 am to 10 pm.\nSaturday: 9 am to 6 pm.\nClosed on Sunday." }'Adds a text file (.txt or .md) to the base and reads it at once:
when the call answers, every agent that answers from the base can use
it on its next reply. The text is cut into passages exactly like a
file uploaded from the Knowledge page. A name without an extension
gets .txt. A base cannot hold two files of the same name (409):
rewrite the existing one instead. Two calls that add the same name at
the same moment leave one file; the other call answers 409.
PDF and Word files are uploaded from the dashboard. A plan that adds
no knowledge, or a base that already holds the files its plan allows
(files_limit), answers 402. Requires scope knowledge:write.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”A base id from GET /knowledge-bases, or a campaign’s knowledge_base_id
Request Bodyrequired
Section titled “Request Bodyrequired”object
The file name shown in the dashboard, ending in .txt or .md.
The whole text of the file.
Example
{ "name": "opening-hours.txt", "text": "Monday to Friday: 7 am to 10 pm.\nSaturday: 9 am to 6 pm.\nClosed on Sunday."}Responses
Section titled “Responses”The file, ready
object
object
PDF files read from the dashboard; null otherwise.
How many passages the agents hold for this file: what the search picks from.
true for a text file (.txt, .md).
The length of the file’s text.
Example
{ "data": { "id": "68e61c2a0019f0a4d3b1", "name": "opening-hours.txt", "status": "ready", "size_bytes": 72, "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", "revision": "5f2a9c81d04be637", "characters": 72 }}Missing, unknown or revoked API key
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}The plan adds no knowledge, or the base holds all the files its plan allows
object
object
Example
{ "error": { "code": "plan_limit_reached", "message": "This knowledge base already holds the files its plan allows. Remove one, or rewrite an existing one." }}The key lacks the required scope (insufficient_scope), the plan does not have this part of the API (not_in_plan), or Instagram is not enabled on the workspace (instagram_not_enabled, Instagram routes)
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Resource not found in this workspace
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}The base already holds a file of that name
object
object
Example
{ "error": { "code": "invalid_state", "message": "A file named \"opening-hours.txt\" already exists in this knowledge base (id 68e61c2a0019f0a4d3b1). Rewrite it with PATCH, or choose another name." }}A missing, empty or too long field, or a name that is not a text file
object
object
Example
{ "error": { "code": "validation_error", "message": "The API adds text files: a name ending in .txt or .md, not .pdf. PDF and Word files are uploaded from the dashboard." }}A store did not answer. The message says whether anything was written; read the base again before retrying.
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}