> ## 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.
# List app files
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Lists the files and directories in 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.
Defaults to the app root, one level deep. Set `path` to list a subtree, and `recursive: true` to go deeper, up to `max_depth` (3 by default, 10 at most). Dotfiles are left out unless you set `include_hidden`.
Directory entries carry no `size`; files do. Listings are capped at 1000 entries with `truncated` reporting it, and Base44's own protected trees never appear. Dependency and build directories such as `node_modules`, `dist` and `build` are pruned, so the listing stays the app's own source.
A `path` that exists but isn't a directory answers 400, and one that doesn't exist answers 404.
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/list_directory
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/list_directory:
post:
summary: List app files
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Lists the files and directories in 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.
Defaults to the app root, one level deep. Set `path` to list a subtree,
and `recursive: true` to go deeper, up to `max_depth` (3 by default, 10
at most). Dotfiles are left out unless you set `include_hidden`.
Directory entries carry no `size`; files do. Listings are capped at 1000
entries with `truncated` reporting it, and Base44's own protected trees
never appear. Dependency and build directories such as `node_modules`,
`dist` and `build` are pruned, so the listing stays the app's own
source.
A `path` that exists but isn't a directory answers 400, and one that
doesn't exist answers 404.
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: >-
list_directory_endpoint_api_apps__app_id__sandbox_bridge_list_directory_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: ListAppFiles
properties:
path:
anyOf:
- type: string
- type: 'null'
description: 'Directory relative to the app root. Default: app root.'
title: Path
recursive:
default: false
description: List nested entries.
title: Recursive
type: boolean
max_depth:
default: 3
description: Max depth when recursive.
maximum: 10
minimum: 1
title: Max Depth
type: integer
include_hidden:
default: false
description: Include dotfiles.
title: Include Hidden
type: boolean
required: []
example:
path: src
recursive: true
max_depth: 2
required: true
responses:
'200':
description: The listing.
content:
application/json:
schema:
$ref: '#/components/schemas/ListDirectoryResult'
'400':
description: >-
`path` isn't a directory, points outside the app, or at a protected
path.
'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, or `path` doesn't exist.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded (120 requests per minute).
components:
schemas:
ListDirectoryResult:
properties:
entries:
items:
$ref: '#/components/schemas/DirectoryEntry'
type: array
title: Entries
description: Files and directories, capped at 1000 entries.
example:
- name: pages
path: src/pages
type: directory
- name: Home.jsx
path: src/pages/Home.jsx
size: 214
type: file
truncated:
type: boolean
title: Truncated
description: >-
`true` when the listing hit the 1000-entry cap. Narrow it with
`path` or a smaller `max_depth`.
example: false
type: object
required:
- entries
- truncated
title: ListDirectoryResult
description: The listing, and whether you got all of it.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
DirectoryEntry:
properties:
name:
type: string
title: Name
description: The entry's own name, without its parent path.
example: Home.jsx
path:
type: string
title: Path
description: Full path relative to the app root.
example: src/pages/Home.jsx
type:
type: string
enum:
- file
- directory
title: Type
description: Whether the entry is a file or a directory.
example: file
size:
anyOf:
- type: integer
- type: 'null'
title: Size
description: Size in bytes. Present on files, absent on directories.
example: 214
type: object
required:
- name
- path
- type
title: DirectoryEntry
description: One file or directory.
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
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````