# Rewrite a text file

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

Changes the text of a file whose `editable` is `true`. The agents use
the new text on their next reply, and never see the file empty in
between: the new passages are stored before the old ones are
withdrawn. Send one of:

- `edits`: replacements inside the current text, applied in order.
  Each `find` must sit **exactly once** in the text as it stands when
  its turn comes. If one is missing or sits several times, the call
  answers `422` and **nothing** is applied. This is the safe way to
  change a price or an opening hour without touching the rest.
- `text`: the whole new text.

The file keeps its `id` and its name. The previous text is not kept:
read it first if it may be wanted back. Sending a text identical to
the current one answers `changed: false`.

**One change at a time.** Pass the `revision` you read as
`if_revision`: the change is refused (`409`) when the file is no
longer that text. 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`
as well. Put several replacements in one `edits` list rather than in
several calls.

A change that was cut short (a `502` that says « may be partly
applied ») leaves the file between two texts. For a minute and a half
every change of that file answers `409`. After that, read the file:
it returns the text that was saved, and the next change starts from
it and puts the file back in order.

A `502` says in its message what the file holds: either nothing was
changed, or the change may be partly applied.

A PDF or Word file cannot be rewritten in place (`409`), nor a file
that is still being read. Works on every plan. Requires scope
`knowledge:write`.

## Parameters

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

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `edits` | array | no |  |
| `text` | string | no |  |
| `if_revision` | string | no | The `revision` a read of this file returned. The change is refused when the file is no longer that text. |

```json
{
  "edits": [
    {
      "find": "Saturday: 9 am to 6 pm.",
      "replace": "Saturday: 9 am to 8 pm."
    }
  ],
  "if_revision": "5f2a9c81d04be637"
}
```

## Example request

```bash
curl --request PATCH \
  --url 'https://app.whatsetter.com/api/v1/knowledge-bases/{id}/files/{fileId}' \
  --header 'Authorization: Bearer ws_live_…'
  --header 'Content-Type: application/json' \
  --data '{"edits":[{"find":"Saturday: 9 am to 6 pm.","replace":"Saturday: 9 am to 8 pm."}],"if_revision":"5f2a9c81d04be637"}'
```

## Responses

### 200: The file after the change

```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-09T09:02:31.000+00:00",
    "changed": true,
    "revision": "c41d7e0a92b3f586",
    "characters": 72,
    "previous_characters": 72
  }
}
```

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

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

### 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: Not a text file, a file still being read, a text that is no longer the one of `if_revision`, another change of the file being saved, or a file whose saved text cannot be told after a change that was cut short (send its whole text then, without `if_revision`). Nothing was changed.

```json
{
  "error": {
    "code": "invalid_state",
    "message": "This file is no longer the one you read: its text changed since. Nothing was changed. Read it again, then retry with its new \"revision\"."
  }
}
```

### 422: Neither or both of `text` and `edits`, an empty or too long text, or an edit that does not point to one place

```json
{
  "error": {
    "code": "validation_error",
    "message": "edits[0].find is in the file 3 times: add the text around it so it points to one place. Nothing was changed."
  }
}
```

### 502: A store did not answer. The message says whether nothing was changed, or whether the change may be partly applied. In that case read the file again after two minutes (it returns the text that was saved) and send the change again if it is not in it.

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


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