# Add a text file

`POST https://app.whatsetter.com/api/v1/knowledge-bases/{id}/files`

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

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | The file name shown in the dashboard, ending in `.txt` or `.md`. |
| `text` | string | yes | The whole text of the file. |

```json
{
  "name": "opening-hours.txt",
  "text": "Monday to Friday: 7 am to 10 pm.\nSaturday: 9 am to 6 pm.\nClosed on Sunday."
}
```

## Example request

```bash
curl --request POST \
  --url 'https://app.whatsetter.com/api/v1/knowledge-bases/{id}/files' \
  --header 'Authorization: Bearer ws_live_…'
  --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."}'
```

## Responses

### 201: The file, ready

```json
{
  "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
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

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

```json
{
  "error": {
    "code": "plan_limit_reached",
    "message": "This knowledge base already holds the files its plan allows. Remove one, or rewrite an existing one."
  }
}
```

### 403: 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)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 404: Resource not found in this workspace

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 409: The base already holds a file of that name

```json
{
  "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."
  }
}
```

### 422: A missing, empty or too long field, or a name that is not a text file

```json
{
  "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."
  }
}
```

### 502: A store did not answer. The message says whether anything was written; read the base again before retrying.

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```


Source: https://docs.whatsetter.com/api-reference/operations/createknowledgefile/
