> ## 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.
# Read app files
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
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.
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`.
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/read_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/read_file:
post:
summary: Read app files
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
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.
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`.
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: read_file_endpoint_api_apps__app_id__sandbox_bridge_read_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: ReadAppFiles
properties:
paths:
description: One or more file paths relative to the app root.
items:
type: string
maxItems: 50
minItems: 1
title: Paths
type: array
offset:
anyOf:
- minimum: 1
type: integer
- type: 'null'
description: 1-based start line (optional).
title: Offset
limit:
anyOf:
- minimum: 1
type: integer
- type: 'null'
description: Max lines to return from offset (optional).
title: Limit
required:
- paths
example:
paths:
- src/pages/Home.jsx
- package.json
required: true
responses:
'200':
description: One entry per requested path, each either a read or an error.
content:
application/json:
schema:
$ref: '#/components/schemas/ReadFileResult'
'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.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded (120 requests per minute).
components:
schemas:
ReadFileResult:
properties:
files:
items:
$ref: '#/components/schemas/ReadFileEntry'
type: array
title: Files
description: >-
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`.
example:
- content: |
export default function Home() {
return Hello
;
}
end_line: 3
path: src/pages/Home.jsx
start_line: 1
total_lines: 3
truncated: false
- error:
code: NOT_FOUND
message: File not found.
path: src/pages/Missing.jsx
type: object
required:
- files
title: ReadFileResult
description: The files you asked for, in the order you asked for them.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ReadFileEntry:
properties:
path:
type: string
title: Path
description: >-
The path you asked for, echoed back so you can match entries to your
request. The only field present on every entry.
example: src/pages/Home.jsx
content:
anyOf:
- type: string
- type: 'null'
title: Content
description: >-
The file's text over the returned line range. Absent when this path
failed.
example: |
export default function Home() {
return Hello
;
}
start_line:
anyOf:
- type: integer
- type: 'null'
title: Start Line
description: First line included, 1-based. Absent when this path failed.
example: 1
end_line:
anyOf:
- type: integer
- type: 'null'
title: End Line
description: Last line included, 1-based. Absent when this path failed.
example: 3
total_lines:
anyOf:
- type: integer
- type: 'null'
title: Total Lines
description: >-
How many lines the whole file has, so you can tell whether you
received all of it. Absent when this path failed.
example: 3
truncated:
anyOf:
- type: boolean
- type: 'null'
title: Truncated
description: >-
`true` when this entry was cut short, either by your `limit` or by
the 1 MB per-file cap. Absent when this path failed.
example: false
error:
anyOf:
- $ref: '#/components/schemas/ReadFileError'
- type: 'null'
description: >-
Why this path could not be read, and absent when it could. Its
presence is what marks a failed entry.
type: object
required:
- path
title: ReadFileEntry
description: >-
One path from a read request: either its contents or why it failed.
Every field except ``path`` is absent-able, because an entry is one of
two
shapes. A successful read carries the five content fields and no
``error``;
a failed one carries ``error`` and nothing else.
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
ReadFileError:
properties:
code:
type: string
title: Code
description: >-
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.
example: NOT_FOUND
message:
type: string
title: Message
description: Human-readable explanation for this path.
example: File not found.
type: object
required:
- code
- message
title: ReadFileError
description: Why one path in the batch could not be read.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````