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

# Write an app file

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

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

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.

<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](/api-reference/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>

## Path parameters

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

## Request body

- object
  - `branch_id` string, nullable — Optional Base44 branch ID. Omit to operate on main.
  - `path` string, required — File path relative to the app root.
  - `content` string, required — 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.
  - `overwrite` boolean — Must be true to overwrite an existing file (destructive). Default false never clobbers.

## Response `200`

The file was written.

- WriteFileResult — What the write did.
  - `path` string, required — The normalized path that was written.
  - `bytes_written` integer, required — Size of the content written, in bytes.
  - `created` boolean, required — `true` when the file did not exist before this call.
  - `overwritten` boolean, required — `true` when the file existed and was replaced. Never `true` unless you sent `overwrite`.
  - `warnings` string[], required — Advisories about the write that did not stop it, such as writing somewhere the builder treats specially. Empty when there are none.

## Other responses

- `400` — 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.
- `409` — 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` — The content is larger than the 6 MB cap.
- `422` — Validation Error
- `429` — Rate limit exceeded (60 requests per minute).

## Changes

- **2026-09-15** `0e0a206b2f33` — 1 info
  - added the new optional request property `branch_id`
- **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/write_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/cf164639a9bf?raw)