Grep

Search for a regex pattern across files in the agent’s workspace

POST /v1/agents/{agent_id}/workspace/grep

Workspace: Grep

cURL

curl --request POST \
  --url https://api.xpander.ai/v1/agents/{agent_id}/workspace/grep \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "pattern": "world",
  "include": "*.txt"
}
'

200

{
  "matches": [
    {
      "file": "/notes/demo.txt",
      "line": 1,
      "content": "hello, world",
      "context": "/agent/data/notes/demo.txt:1:hello, world"
    }
  ],
  "total_matches": 1,
  "files_with_matches": 1,
  "summary": "1 match(es) across 1 file(s) for /world/"
}

Search for a regex pattern across files in the per-agent workspace, with optional file-type filtering and surrounding context lines.

Path Parameters

agent_id · string · required

Agent ID (UUID)

Request Body

pattern · string · required

Regular expression to search for.

path · string

Directory or file path to search, relative to the workspace root.

include · string

Optional filename glob to include (e.g. *.py).

context_lines · integer · default: 0

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

Response

matches · array

One entry per matching line, with file, line, content and context (the line with its surrounding lines).

total_matches · integer

Number of matching lines.

files_with_matches · integer

Number of files that matched.

summary · string

A one-line summary, for example 1 match(es) in 1 file(s).

Example Request

curl -X POST "https://api.xpander.ai/v1/agents/<agent-id>/workspace/grep" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "pattern": "def main",
    "path": "src",
    "include": "*.py",
    "context_lines": 2
  }'

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

• Glob
• File Read

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

200

application/json

Successful Response

matches · GrepMatch · object[]

List of matched results with context

Show child attributes

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