> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shinzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Files

> Search for files by name or content within an agent's workspace.

## Authentication

Requires JWT token or Platform API key.

<ParamField path="agentId" type="string" required>Agent UUID</ParamField>
<ParamField body="query" type="string" required>Search pattern (glob for filenames, regex for content)</ParamField>
<ParamField body="type" type="string">Search type: `filename`, `content`, or `both`</ParamField>
<ParamField body="path" type="string">Base path to search from (defaults to workspace root)</ParamField>
<ParamField body="filePattern" type="string">Glob pattern for file matching</ParamField>
<ParamField body="caseSensitive" type="boolean">Enable case-sensitive matching</ParamField>
<ParamField body="maxResults" type="number">Maximum results to return</ParamField>

## Example Request

Search for files by name:

```bash theme={null}
curl -X POST "https://api.app.shinzo.ai/v1/agent/agt_abc123/filesystem/operations/search" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "*.json",
    "path": "/workspace/config",
    "max_results": 50
  }'
```

Search file contents:

```bash theme={null}
curl -X POST "https://api.app.shinzo.ai/v1/agent/agt_abc123/filesystem/operations/search" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "TODO",
    "content_search": true,
    "case_sensitive": false
  }'
```

## Response

```json theme={null}
{
  "results": [
    {
      "path": "/workspace/config/settings.json",
      "type": "file",
      "size": 256
    },
    {
      "path": "/workspace/config/env.json",
      "type": "file",
      "size": 128
    }
  ],
  "total": 2
}
```

For content searches, results include match details:

```json theme={null}
{
  "results": [
    {
      "path": "/workspace/src/index.js",
      "type": "file",
      "size": 1024,
      "matches": [
        "// TODO: implement error handling"
      ]
    }
  ],
  "total": 1
}
```

## Response Fields

| Field               | Type   | Description                                  |
| ------------------- | ------ | -------------------------------------------- |
| `results`           | array  | List of matching files                       |
| `results[].path`    | string | File path                                    |
| `results[].type`    | string | Entry type (`file` or `directory`)           |
| `results[].size`    | number | File size in bytes                           |
| `results[].matches` | array  | Matching content lines (content search only) |
| `total`             | number | Total number of results                      |

## Status Codes

| Code  | Description                     |
| ----- | ------------------------------- |
| `200` | Search completed successfully   |
| `400` | Invalid request body or pattern |
| `401` | Invalid authentication          |
| `403` | Access denied                   |
| `404` | Agent not found                 |