---
title: "Edit an app file"
method: POST
path: "/api/apps/{app_id}/sandbox-bridge/edit_file"
---

# Edit an app file

`POST /api/apps/{app_id}/sandbox-bridge/edit_file`

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Applies exact-string edits to a file in the app's sandbox and returns the diff.

Every sandbox-bridge endpoint runs against the app's live sandbox, the same filesystem the Base44 builder edits, so a change here is visible in the builder immediately.

Send up to 100 edits and Base44 applies them in order, all or nothing: if any one fails to match, the file is left untouched and the request answers 400. Each `old_text` has to match exactly, and has to be unique in the file unless you set `replace_all` on that edit.

Set `dry_run: true` to get the same `diff` back without writing. A dry run answers with `applied` as `false` and no `warnings` key at all, so read `applied` rather than checking for warnings. A dry run still needs write access, because it is the edit tool.

Prefer this over [Write an app file](/api-reference/write-an-app-file) for changing part of a file: you send only the strings involved, and the response shows exactly what changed.

This endpoint is limited to 60 requests per minute per app, shared with the other sandbox-bridge endpoints that change files.

<Note>The sandbox bridge needs a Builder plan or higher on the app's workspace, and answers 402 below that. Workspace API keys are not authorized and are rejected with a 403, and it is unavailable for agent apps. A personal API key works as-is. An OAuth access token needs the `sandbox:write` scope.</Note>

<Tip>Every error response carries a stable `extra_data.code` alongside the human-readable `message`. Branch on the code rather than on the message text or the status.</Tip>

## Path parameters

- `app_id` string, required — ID of the app whose sandbox to operate on.

## Request body

- object
  - `path` string, required — File path relative to the app root.
  - `edits` object[], required — Ordered exact-string edits. Applied all-or-nothing.
    - `old_text` string, required — Exact text to find. Must be unique in the file unless replace_all is true. Cannot be empty.
    - `new_text` string, required — Replacement text.
    - `replace_all` boolean — Replace every occurrence instead of requiring uniqueness.
  - `dry_run` boolean — Return the unified diff without writing.

## Response `200`

The diff, applied unless you asked for a dry run.

- EditFileResult — The diff, and whether it landed.
  - `path` string, required — The normalized path that was edited.
  - `diff` string, required — Unified diff of the change, whether or not it was applied.
  - `applied` boolean, required — `true` when the file was changed, `false` on a `dry_run` preview.
  - `warnings` string[], nullable — Advisories about the write that did not stop it. Absent entirely on a `dry_run`, since nothing was written.

## Other responses

- `400` — An `old_text` didn't match, matched more than once without `replace_all`, the edits would empty the file, or the path points outside the app or at a protected path.
- `401` — Missing or invalid credentials.
- `402` — The app's workspace plan doesn't include the sandbox bridge.
- `403` — You don't have access to this app, the app is blocked, your OAuth token is missing the scope this endpoint needs, or you used a workspace API key.
- `404` — App not found, or the file doesn't exist.
- `409` — The app is on a branch that can't be written to: a protected main, or a branch that has been merged or closed.
- `413` — The resulting file would be larger than the 6 MB cap.
- `422` — The file is binary.
- `429` — Rate limit exceeded (60 requests per minute).

## Changes

- **2026-09-07** `78b01bcee66e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/base44/apis/base44-app-management-api/changes/api/apps/:app_id/sandbox-bridge/edit_file/post.md)

---

[API](https://skmtc.dev/base44/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/base44/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/base44/apis/base44-app-management-api/revisions/78b01bcee66e?raw)