> ## 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.
# Search app files
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Searches the app's files for a pattern and returns the matching lines.
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.
The pattern is a regular expression by default; set `is_regex: false` to match it literally. Narrow the search with `path` to a subtree and `glob` to a filename pattern. Matching is case-insensitive unless you set `case_sensitive`.
Finding nothing is a 200 with an empty `matches`, not a 404. Results are capped at `max_results` (200 by default, 1000 at most) and the output at 1 MB, and `truncated` tells you when either cap bit, so treat a `true` there as "narrow the search" rather than "no more matches".
Base44 keeps its own protected trees out of the results, so a pattern that exists only there returns nothing.
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/grep
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/grep:
post:
summary: Search app files
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Searches the app's files for a pattern and returns the matching lines.
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.
The pattern is a regular expression by default; set `is_regex: false` to
match it literally. Narrow the search with `path` to a subtree and
`glob` to a filename pattern. Matching is case-insensitive unless you
set `case_sensitive`.
Finding nothing is a 200 with an empty `matches`, not a 404. Results are
capped at `max_results` (200 by default, 1000 at most) and the output at
1 MB, and `truncated` tells you when either cap bit, so treat a `true`
there as "narrow the search" rather than "no more matches".
Base44 keeps its own protected trees out of the results, so a pattern
that exists only there returns nothing.
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: grep_endpoint_api_apps__app_id__sandbox_bridge_grep_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: SearchAppFiles
properties:
pattern:
description: Search pattern.
title: Pattern
type: string
path:
anyOf:
- type: string
- type: 'null'
description: >-
Subtree to search, relative to the app root. Default: whole
app.
title: Path
is_regex:
default: true
description: Treat the pattern as a regex (default) or a literal string.
title: Is Regex
type: boolean
case_sensitive:
default: false
description: Case-sensitive match. Default false.
title: Case Sensitive
type: boolean
glob:
anyOf:
- type: string
- type: 'null'
description: Optional file glob filter, e.g. "*.tsx".
title: Glob
max_results:
default: 200
description: Maximum number of match lines to return.
maximum: 1000
minimum: 1
title: Max Results
type: integer
required:
- pattern
example:
pattern: useState
path: src
glob: '*.jsx'
max_results: 50
required: true
responses:
'200':
description: The matching lines, empty when nothing matched.
content:
application/json:
schema:
$ref: '#/components/schemas/GrepResult'
'400':
description: '`path` 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:
GrepResult:
properties:
matches:
items:
$ref: '#/components/schemas/GrepMatch'
type: array
title: Matches
description: Matching lines, capped at `max_results`.
example:
- line: 2
path: src/pages/Home.jsx
text: ' return Hello
;'
truncated:
type: boolean
title: Truncated
description: >-
`true` when there was more to return: either more matches than
`max_results`, or output that hit the 1 MB cap. One very long line
can set this with few matches.
example: false
returned_matches:
type: integer
title: Returned Matches
description: How many entries `matches` holds.
example: 1
type: object
required:
- matches
- truncated
- returned_matches
title: GrepResult
description: The matches, and whether you got all of them.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
GrepMatch:
properties:
path:
anyOf:
- type: string
- type: 'null'
title: Path
description: >-
File the match is in, relative to the app root. `null` on a match
line Base44 couldn't split into path, line and text, where the whole
line lands in `text` instead.
example: src/pages/Home.jsx
line:
anyOf:
- type: integer
- type: 'null'
title: Line
description: >-
1-based line number of the match, and `null` in the same case `path`
is.
example: 2
text:
type: string
title: Text
description: >-
The matching line. Always populated, so it's the field to fall back
on.
example: ' return Hello
;'
type: object
required:
- path
- line
- text
title: GrepMatch
description: One matching line.
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.
````