> ## 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.
# Write an app file
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Writes a whole file into the app's sandbox, creating it or replacing it.
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.
The default refuses to clobber: writing a path that already exists answers 409 unless you send `overwrite: true`. Read `created` and `overwritten` on the response to see which happened.
`content` cannot be empty. The builder's write path reads empty content as a delete, so this endpoint rejects it rather than deleting a file behind a write call. To create an empty file, run `touch` through [Run a sandbox command](/api-reference/run-a-sandbox-command); to change part of a file, use [Edit an app file](/api-reference/edit-an-app-file), which is cheaper than sending the whole thing.
Base44 refuses paths outside the app and a set of protected paths, both with a 400. A file over the 6 MB cap answers 413.
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/write_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/write_file:
post:
summary: Write an app file
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Writes a whole file into the app's sandbox, creating it or replacing it.
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.
The default refuses to clobber: writing a path that already exists
answers 409 unless you send `overwrite: true`. Read `created` and
`overwritten` on the response to see which happened.
`content` cannot be empty. The builder's write path reads empty content
as a delete, so this endpoint rejects it rather than deleting a file
behind a write call. To create an empty file, run `touch` through [Run a
sandbox command](/api-reference/run-a-sandbox-command); to change part
of a file, use [Edit an app file](/api-reference/edit-an-app-file),
which is cheaper than sending the whole thing.
Base44 refuses paths outside the app and a set of protected paths, both
with a 400. A file over the 6 MB cap answers 413.
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: write_file_endpoint_api_apps__app_id__sandbox_bridge_write_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: WriteAppFile
properties:
path:
description: File path relative to the app root.
title: Path
type: string
content:
description: >-
Full file content to write. To create an empty file (e.g.
.gitkeep) use run_command (touch) — the platform write path
treats empty content as a delete.
maxLength: 6000000
minLength: 1
title: Content
type: string
overwrite:
default: false
description: >-
Must be true to overwrite an existing file (destructive).
Default false never clobbers.
title: Overwrite
type: boolean
required:
- path
- content
example:
path: src/pages/About.jsx
content: |
export default function About() {
return About
;
}
required: true
responses:
'200':
description: The file was written.
content:
application/json:
schema:
$ref: '#/components/schemas/WriteFileResult'
'400':
description: 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.
'409':
description: >-
The file exists and you didn't send `overwrite`, the app is on a
branch that can't be written to, or an earlier change is still being
committed.
'413':
description: The content is larger than the 6 MB cap.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded (60 requests per minute).
components:
schemas:
WriteFileResult:
properties:
path:
type: string
title: Path
description: The normalized path that was written.
example: src/pages/About.jsx
bytes_written:
type: integer
title: Bytes Written
description: Size of the content written, in bytes.
example: 214
created:
type: boolean
title: Created
description: '`true` when the file did not exist before this call.'
example: true
overwritten:
type: boolean
title: Overwritten
description: >-
`true` when the file existed and was replaced. Never `true` unless
you sent `overwrite`.
example: false
warnings:
items:
type: string
type: array
title: Warnings
description: >-
Advisories about the write that did not stop it, such as writing
somewhere the builder treats specially. Empty when there are none.
example: []
type: object
required:
- path
- bytes_written
- created
- overwritten
- warnings
title: WriteFileResult
description: What the write did.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````