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

> <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 AI edits, so a change here is visible in the app editor 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.

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](/api-reference/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`. The bridge is unavailable for agent apps. A personal API key works as-is, and so does a workspace API key, which acts as the workspace owner. 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>



## 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:
  - PersonalAccessTokenAuth: []
paths:
  /api/apps/{app_id}/sandbox-bridge/edit_file:
    post:
      summary: Edit an app file
      description: >-
        <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 AI edits, so a change here is visible in the app
        editor 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.


        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](/api-reference/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`. The
        bridge is unavailable for agent apps. A personal API key works as-is,
        and so does a workspace API key, which acts as the workspace owner. 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>
      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:
                branch_id:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: Optional Base44 branch ID. Omit to operate on main.
                  title: Branch Id
                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: <h1>Hello</h1>
                  new_text: <h1>Welcome</h1>
        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, the path points
            outside the app or at a protected path, or it is an entity file that
            would define an invalid entity name (`INVALID_ENTITY_NAME`).
        '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, or your OAuth
            token is missing the scope this endpoint needs.
        '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. Also answered with
            `UNMANAGED_SOURCE_CODE` when the app's source code is managed
            outside Base44, for example with the Base44 CLI.
        '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).
      security:
        - PersonalAccessTokenAuth:
            - full_access
        - WorkspaceApiKeyAuth:
            - full_access
        - WorkspaceApiKeyBearerAuth:
            - full_access
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 <h1>Hello</h1>;
            +  return <h1>Welcome</h1>;
        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:
    PersonalAccessTokenAuth:
      type: http
      scheme: bearer
      description: >-
        Personal access token, sent as `Authorization: Bearer <token>`. Each
        operation lists the permission it needs: `read_only` or `full_access`. A
        full-access token can call every operation. A read-only token can call
        only the operations that list `read_only`; anything else returns 403
        `read_only_credential_route_not_allowed`.
    WorkspaceApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: >-
        Workspace API key, sent as `api_key: <key>`. Each operation that accepts
        one lists what the key needs: a permission, `read_only` or
        `full_access`, like a personal access token, or a scope. A key without
        the scope gets 403 `workspace_api_key_scope_required`.
    WorkspaceApiKeyBearerAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace API key, sent as `Authorization: Bearer <key>`. Accepted
        wherever `api_key` is, with the same permission.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.