Skip to content
Dashboard

Add a text file

POST
/knowledge-bases/{id}/files
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.

id
required

A base id from GET /knowledge-bases, or a campaign’s knowledge_base_id

string
Media typeapplication/json
object
name
required

The file name shown in the dashboard, ending in .txt or .md.

string
>= 1 characters <= 120 characters
text
required

The whole text of the file.

string
>= 1 characters <= 200000 characters
Example
{
"name": "opening-hours.txt",
"text": "Monday to Friday: 7 am to 10 pm.\nSaturday: 9 am to 6 pm.\nClosed on Sunday."
}

The file, ready

Media typeapplication/json
object
data
object
id
string
name
string | null
status
string
Allowed values: ready reading failed empty
size_bytes
integer | null
pages

PDF files read from the dashboard; null otherwise.

integer | null
passages

How many passages the agents hold for this file: what the search picks from.

integer
editable

true for a text file (.txt, .md).

boolean
created_at
string | null format: date-time
updated_at
string | null format: date-time
characters

The length of the file’s text.

integer
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

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

The plan adds no knowledge, or the base holds all the files its plan allows

Media typeapplication/json
object
error
object
code
string
message
string
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)

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

Resource not found in this workspace

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

The base already holds a file of that name

Media typeapplication/json
object
error
object
code
string
message
string
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

Media typeapplication/json
object
error
object
code
string
message
string
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.

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}