> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Edit an app file
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
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.
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.
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.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/sandbox-bridge/edit_file
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- ApiKeyAuth: []
paths:
/api/apps/{app_id}/sandbox-bridge/edit_file:
post:
summary: Edit an app file
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
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.
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.
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.
operationId: edit_file_endpoint_api_apps__app_id__sandbox_bridge_edit_file_post
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app whose sandbox to operate on.
title: App Id
description: ID of the app whose sandbox to operate on.
example: 6820f3a4e7b91d003c45a1f2
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: false
default: {}
title: EditAppFile
properties:
path:
description: File path relative to the app root.
title: Path
type: string
edits:
description: Ordered exact-string edits. Applied all-or-nothing.
items:
additionalProperties: false
properties:
old_text:
description: >-
Exact text to find. Must be unique in the file unless
replace_all is true. Cannot be empty.
minLength: 1
title: Old Text
type: string
new_text:
description: Replacement text.
title: New Text
type: string
replace_all:
default: false
description: >-
Replace every occurrence instead of requiring
uniqueness.
title: Replace All
type: boolean
required:
- old_text
- new_text
title: _Edit
type: object
maxItems: 100
minItems: 1
title: Edits
type: array
dry_run:
default: false
description: Return the unified diff without writing.
title: Dry Run
type: boolean
required:
- path
- edits
example:
path: src/pages/Home.jsx
edits:
- old_text: Hello
new_text: Welcome
required: true
responses:
'200':
description: The diff, applied unless you asked for a dry run.
content:
application/json:
schema:
$ref: '#/components/schemas/EditFileResult'
'400':
description: >-
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':
description: Missing or invalid credentials.
'402':
description: The app's workspace plan doesn't include the sandbox bridge.
'403':
description: >-
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':
description: App not found, or the file doesn't exist.
'409':
description: >-
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':
description: The resulting file would be larger than the 6 MB cap.
'422':
description: The file is binary.
'429':
description: Rate limit exceeded (60 requests per minute).
components:
schemas:
EditFileResult:
properties:
path:
type: string
title: Path
description: The normalized path that was edited.
example: src/pages/Home.jsx
diff:
type: string
title: Diff
description: Unified diff of the change, whether or not it was applied.
example: |
--- src/pages/Home.jsx
+++ src/pages/Home.jsx
@@ -1,3 +1,3 @@
- return Hello
;
+ return Welcome
;
applied:
type: boolean
title: Applied
description: '`true` when the file was changed, `false` on a `dry_run` preview.'
example: true
warnings:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Warnings
description: >-
Advisories about the write that did not stop it. Absent entirely on
a `dry_run`, since nothing was written.
example: []
type: object
required:
- path
- diff
- applied
title: EditFileResult
description: The diff, and whether it landed.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````