---
title: "Exact-string edit of a text file"
method: POST
path: "/v1/filesystem/edit-file"
tags: ["Files"]
---

# Exact-string edit of a text file

`POST /v1/filesystem/edit-file`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/filesystem/edit-file`
- Auth: HTTP bearer

Replaces an exact `old_text` span with `new_text`. Fails 422 on zero
or (without `replace_all`) multiple matches, 409 when `revision`
(from a prior read) no longer matches the bytes on disk, and 415 on
binary files. Matching is literal (no Unicode normalization).

## Request body

- object
  - `path` string, required: Absolute path (tilde expanded) of the file to edit
  - `old_text` string, required: Exact span to replace; must not be empty
  - `new_text` string, required
  - `replace_all` boolean
  - `revision` string: Revision hash from a prior file read; 409 on mismatch

## Response `200`

Edit applied

- object
  - `path` string, required
  - `replacements` integer, required
  - `revision` string, required: Hash of the post-edit file content

## Other responses

- `404`: File not found
- `409`: Revision mismatch — file changed on disk since the last read
- `422`: old_text matched zero or multiple spans

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)