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

# Search app files

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

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

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.

<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.
  - `pattern` string, required — Search pattern.
  - `path` string, nullable — Subtree to search, relative to the app root. Default: whole app.
  - `is_regex` boolean — Treat the pattern as a regex (default) or a literal string.
  - `case_sensitive` boolean — Case-sensitive match. Default false.
  - `glob` string, nullable — Optional file glob filter, e.g. "*.tsx".
  - `max_results` integer — Maximum number of match lines to return.

## Response `200`

The matching lines, empty when nothing matched.

- GrepResult — The matches, and whether you got all of them.
  - `matches` GrepMatch[], required — Matching lines, capped at `max_results`.
    - `path` string, nullable, required — 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.
    - `line` integer, nullable, required — 1-based line number of the match, and `null` in the same case `path` is.
    - `text` string, required — The matching line. Always populated, so it's the field to fall back on.
  - `truncated` boolean, required — `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.
  - `returned_matches` integer, required — How many entries `matches` holds.

## Other responses

- `400` — `path` points outside the app, or at a protected path.
- `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, or `path` doesn't exist.
- `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/grep/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/0e0a206b2f33?raw)