Skip to content
Dashboard

Rewrite a text file

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

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.

id
required
string
fileId
required
string
Media typeapplication/json
object
edits
Array<object>
>= 1 items <= 50 items
object
find
required

The exact text to replace, line breaks included.

string
>= 1 characters <= 5000 characters
replace
required

What takes its place. An empty string removes it.

string
<= 200000 characters
text
string
>= 1 characters <= 200000 characters
if_revision

The revision a read of this file returned. The change is refused when the file is no longer that text.

string
<= 64 characters
Example
{
"edits": [
{
"find": "Saturday: 9 am to 6 pm.",
"replace": "Saturday: 9 am to 8 pm."
}
],
"if_revision": "5f2a9c81d04be637"
}

The file after the change

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
changed

false when the text sent is the one the file already holds.

boolean
revision

The revision of the text the file now holds.

string
characters
integer
previous_characters

The length of the text that was replaced.

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

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.

Media typeapplication/json
object
error
object
code
string
message
string
Example
{
"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\"."
}
}

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

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

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.

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