Skip to main content
POST
Workspace: Grep
Search for a regex pattern across files in the per-agent workspace, with optional file-type filtering and surrounding context lines.

Path Parameters

string
required
Agent ID (UUID)

Request Body

string
required
Regular expression to search for.
string
Directory or file path to search, relative to the workspace root.
string
Optional filename glob to include (e.g. *.py).
integer
default:0
Number of context lines to include before and after each match.

Response

string
Result status (e.g., ok).
array
Array of match objects, each including the file path, matching line, and surrounding context.

Example Request

Notes

  • pattern is a regex. Escape regex metacharacters if you want to match them literally.
  • Narrow the search with path and include for faster results on large workspaces.

See Also

Authorizations

x-api-key
string
header
required

API Key for authentication

Path Parameters

agent_id
string
required

Body

application/json
pattern
string
required

Regex pattern to search for (Extended Regular Expressions).

Example:

"def main"

path
string
default:""

Directory or file path to search in, relative to workspace root. Directories are searched recursively.

Example:

"src"

include
string | null

Glob pattern to filter which files to search (e.g. '*.py' to only search Python files).

Example:

"*.py"

context_lines
integer
default:2

Number of lines of context to show before and after each match.

Required range: 0 <= x <= 20

Response

Successful Response

matches
GrepMatch · object[]

List of matched results with context

total_matches
integer
default:0

Total number of matching lines found

files_with_matches
integer
default:0

Number of distinct files that contained at least one match

summary
string
default:""

Human-readable one-line summary of the search result