Sign in

Edit an app 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 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.

<Warning>A write is committed, not checkpointed. Only checkpoints appear in the builder's version history, and a Restore or Revert there rolls the app back to the last checkpoint and discards everything written after it. Call Create a sandbox checkpoint when you finish a unit of work and before you stop.</Warning>

<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>

post/api/apps/{app_id}/sandbox-bridge/edit_file

Path parameters

app_idstring required

ID of the app whose sandbox to operate on.

ID of the app whose sandbox to operate on.

Request body

branch_idstring nullable

Optional Base44 branch ID. Omit to operate on main.

pathstring required

File path relative to the app root.

dry_runboolean

Return the unified diff without writing.

Response

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

pathstring required

The normalized path that was edited.

diffstring required

Unified diff of the change, whether or not it was applied.

appliedboolean required

true when the file was changed, false on a dry_run preview.

warningsstring[] nullable

Advisories about the write that did not stop it. Absent entirely on a dry_run, since nothing was written.

Example response

{
  "path": "src/pages/Home.jsx",
  "diff": "--- src/pages/Home.jsx\n+++ src/pages/Home.jsx\n@@ -1,3 +1,3 @@\n-  return <h1>Hello</h1>;\n+  return <h1>Welcome</h1>;\n",
  "applied": true,
  "warnings": []
}

Changes