Search Files

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

POST /v1/agent/{agentId}/filesystem/operations/search

Search Files

cURL

curl --request POST \
  --url https://api.app.shinzo.ai/v1/agent/{agentId}/filesystem/operations/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "type": "<string>",
  "path": "<string>",
  "filePattern": "<string>",
  "caseSensitive": true,
  "maxResults": 123
}
'

Authentication

Requires JWT token or Platform API key.

agentId · string · required

Agent UUID

query · string · required

Search pattern (glob for filenames, regex for content)

type · string

Search type: filename, content, or both

path · string

Base path to search from (defaults to workspace root)

filePattern · string

Glob pattern for file matching

caseSensitive · boolean

Enable case-sensitive matching

maxResults · number

Maximum results to return

Example Request

Search for files by name:

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:

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

{
  "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:

{
  "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