---
title: "Search files, node content, Base records, and custom prompts with one pattern (unified grep)"
method: POST
path: "/api/v1/grep"
tags: ["Search"]
---

# Search files, node content, Base records, and custom prompts with one pattern (unified grep)

`POST /api/v1/grep`

## Request

- Base URL: `https://api-docs.busabase.com`
- URL: `https://api-docs.busabase.com/api/v1/grep`
- Auth: none declared

## Request body

- object
  - `pattern` string, required
  - `flags` string
  - `sources` string[]
  - `scope` object
    - `files` object
      - `assetIds` string[]
      - `drivePath` string
      - `mimeTypes` string[]
    - `nodes` object
      - `nodeIds` string[]
      - `types` string[]
    - `records` object
      - `baseIds` string[]
      - `baseSlugs` string[]
  - `maxMatches` integer
  - `contextLines` integer

## Response `200`

Use when you need every exact occurrence of a string or regex, with line and column; for a ranked browse use `search`, and to find a skill or prompt for a job use playbooks search. Streaming regex/literal matches across every in-scope source — Drive/Skill files (each file match carries `owner`: the node it belongs to, e.g. which skill a SKILL.md hit is in, with its folder path), node content (Doc/HTML/whiteboard/workflow), Base records (canonical headCommit.payload, never the truncated search projection), and custom agent prompts (`prompts`: label and body in every locale; a match names nodeId, key, locale, field). Omitted `sources` scans all four. One shared maxMatches budget and one deadline for the whole call: each requested source gets a floor of floor(maxMatches / sources) and unused budget rolls forward, in the fixed order files → nodes → records → prompts. Per-source honest coverage (files keeps missing/stale/unsearchable/errored/notReached; nodes, records and prompts report scanned/errored/notReached). truncated is set when any source truncated or has notReached > 0 — then narrow with `sources`, `scope.records.baseSlugs`, or `scope.files.drivePath` rather than raising maxMatches.

- object
  - `matches` union[], required
    - union
      - object
        - `source` unknown, required
        - `assetId` string, required
        - `fileName` string, required
        - `drivePath` string, required
        - `owner` object
          - `nodeId` string, required
          - `nodeType` string, required
          - `nodeName` string, required
          - `path` string[], required
        - `text` string, required
        - `before` string[], required
        - `after` string[], required
      - object
        - `source` unknown, required
        - `type` 'doc' | 'html' | 'whiteboard' | 'workflow', required
        - `nodeId` string, required
        - `slug` string, required
        - `name` string, required
        - `text` string, required
        - `before` string[], required
        - `after` string[], required
      - object
        - `source` unknown, required
        - `baseId` string, required
        - `baseSlug` string, required
        - `recordId` string, required
        - `fieldSlug` string, required
        - `text` string, required
        - `before` string[], required
        - `after` string[], required
      - object
        - `source` unknown, required
        - `nodeId` string, required
        - `nodeName` string, required
        - `nodeType` string, required
        - `nodeSlug` string, required
        - `key` string, required
        - `label` string
        - `locale` string, required
        - `field` 'label' | 'body', required
        - `text` string, required
        - `before` string[], required
        - `after` string[], required
  - `coverage` object, required
    - `files` object, required
      - `scanned` integer, required
      - `missing` string[], required
      - `stale` string[], required
      - `unsearchable` integer, required
      - `errored` string[], required
      - `notReached` integer, required
    - `nodes` object, required
      - `scanned` integer, required
      - `errored` string[], required
      - `notReached` integer, required
    - `records` object, required
      - `scanned` integer, required
      - `errored` string[], required
      - `notReached` integer, required
    - `prompts` object
      - `scanned` integer, required
      - `errored` string[], required
      - `notReached` integer, required
  - `truncated` boolean, required

---

[API](https://skmtc.dev/busabase/apis/busabase-api.md) · [All operations](https://skmtc.dev/busabase/apis/busabase-api/llms.txt) · [OpenAPI document](https://skmtc.dev/busabase/apis/busabase-api/revisions/bc6a7d5ff4c1?raw)