Knowledge
Rewrite a text file
const url = 'https://app.whatsetter.com/api/v1/knowledge-bases/example/files/example';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"edits":[{"find":"Saturday: 9 am to 6 pm.","replace":"Saturday: 9 am to 8 pm."}],"if_revision":"5f2a9c81d04be637"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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. Eachfindmust sit exactly once in the text as it stands when its turn comes. If one is missing or sits several times, the call answers422and 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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
object
The exact text to replace, line breaks included.
What takes its place. An empty string removes it.
The revision a read of this file returned. The change is refused when the file is no longer that text.
Example
{ "edits": [ { "find": "Saturday: 9 am to 6 pm.", "replace": "Saturday: 9 am to 8 pm." } ], "if_revision": "5f2a9c81d04be637"}Responses
Section titled “Responses”The file after the change
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.
false when the text sent is the one the file already holds.
The revision of the text the file now holds.
The length of the text that was replaced.
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
object
object
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)
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Resource not found in this workspace
object
object
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.
object
object
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
object
object
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.
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}