Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
workspace
/
grep
Workspace: Grep
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": "<string>",
  "path": "",
  "include": "*.py",
  "context_lines": 2
}
'
{
  "matches": [
    {
      "file": "<string>",
      "line": 123,
      "content": "<string>",
      "context": ""
    }
  ],
  "total_matches": 0
}
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

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

​
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

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