---
title: "Read app files"
method: POST
path: "/api/apps/{app_id}/sandbox-bridge/read_file"
---

# Read app files

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

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

Reads one or more files from the app's sandbox.

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.

Ask for up to 50 paths in one call. Set `offset` and `limit` to read a line range instead of whole files, which is what keeps a large file inside the response budget. A successful entry reports `total_lines` and `truncated`, so you can tell a partial read from a complete one.

**A path that fails does not fail the request.** Every per-path problem rides inside the 200 as an `error` on that entry: a file that doesn't exist, one that isn't UTF-8 text, a path outside the app or in a protected tree, the point where the batch exhausts its aggregate read budget, and a read the sandbox itself refused. So a mixed response is normal, and a request where every path failed is still a 200. Check each entry for `error` before reading `content`, and branch on `error.code`.

This is a read, so a viewer on the workspace can call it and a read-only branch is no obstacle.

This endpoint is limited to 120 requests per minute per app, shared with the other sandbox-bridge endpoints that only read.

<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 `apps:read` scope; the read endpoints don't require `sandbox:write`.</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.
  - `paths` string[], required — One or more file paths relative to the app root.
  - `offset` integer, nullable — 1-based start line (optional).
  - `limit` integer, nullable — Max lines to return from offset (optional).

## Response `200`

One entry per requested path, each either a read or an error.

- ReadFileResult — The files you asked for, in the order you asked for them.
  - `files` ReadFileEntry[], required — One entry per requested path, in request order. Each is either a successful read or an error for that path, so check for `error` before reading `content`.
    - `path` string, required — The path you asked for, echoed back so you can match entries to your request. The only field present on every entry.
    - `content` string, nullable — The file's text over the returned line range. Absent when this path failed.
    - `start_line` integer, nullable — First line included, 1-based. Absent when this path failed.
    - `end_line` integer, nullable — Last line included, 1-based. Absent when this path failed.
    - `total_lines` integer, nullable — How many lines the whole file has, so you can tell whether you received all of it. Absent when this path failed.
    - `truncated` boolean, nullable — `true` when this entry was cut short, either by your `limit` or by the 1 MB per-file cap. Absent when this path failed.
    - `error` ReadFileError — Why one path in the batch could not be read.
      - `code` string, required — Stable machine-readable reason, from the same taxonomy the error responses use: `NOT_FOUND`, `BINARY_FILE`, `PATH_OUTSIDE_SANDBOX`, `PROTECTED_PATH`, `READ_BUDGET_EXCEEDED` or `BACKEND_ERROR`. Branch on this rather than on the message.
      - `message` string, required — Human-readable explanation for this path.

## Other responses

- `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.
- `422` — Validation Error
- `429` — Rate limit exceeded (120 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/read_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)