<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 AI edits, so a change here is visible in the app editor 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 app editor'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; to change part of a file, use 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.

An entity file is named after its entity: base44/entities/TeamMember.jsonc defines TeamMember. A file that would define a new entity whose name isn't letters, numbers and underscores answers 400 with INVALID_ENTITY_NAME, since it would never become a table; the message names the file to write instead.

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 app editor'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 bridge needs a Builder plan or higher on the app's workspace, and answers 402 below that (PREMIUM_REQUIRED). Where sandbox calls are metered, each call is charged to the app's integration credits and a workspace that has none left answers 402 with CREDITS_EXHAUSTED. 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": "src/pages/About.jsx",
  "bytes_written": 214,
  "created": true,
  "warnings": []
}