Search File Content

Search the indexed text of active workspace files and return each matching line with its file id and line number. folderPaths confines the search to one or more folder trees, which also narrows the reported coverage, so complete and indexStatus describe the folders searched rather than the whole workspace. Coverage matters: the index is built asynchronously, so when complete is false a term that was not found is unknown rather than absent, and acting on the absence risks creating a duplicate of something already stored. truncated separately reports that more matches exist beyond maxResults.

GET/api/v2/files/search

Authorization

apiKey
X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.

In: header

Query Parameters

workspaceId*string

Workspace to search.

Length1 <= length <= 128
query*string

Regular expression, or exact text when mode is exact.

Length3 <= length <= 512
mode?string

How query is read.

Default"regex"
Value in"exact" | "regex"
maxResults?integer

Maximum matching lines to return.

Default50
Range1 <= value <= 200
folderPaths?string

Folders the search is confined to, comma-separated. Absent searches the whole workspace. The scope also narrows indexStatus, so complete describes the folders searched rather than the workspace.

includeSubfolders?string

Whether the scope descends into nested folders. Absent means yes. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.

Value in"true" | "1" | "yes" | "on" | "y" | "enabled" | "false" | "0" | "no" | "off" | "n" | "disabled"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://www.sim.ai/api/v2/files/search?workspaceId=string&query=string" \  -H "X-API-Key: YOUR_API_KEY"
{
  "data": {
    "results": [
      {
        "fileId": "wf_V1StGXR8z5jdHi6BmyT91",
        "lineNumber": 4,
        "text": "- based in NYC"
      }
    ],
    "count": 1,
    "truncated": false,
    "complete": true,
    "indexStatus": {
      "readyFiles": 12,
      "pendingFiles": 0,
      "failedFiles": 0,
      "skippedFiles": 0,
      "partialFiles": 0
    }
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key required"
  }
}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}
{
  "error": {
    "code": "LOCKED",
    "message": "The file or its search index is temporarily locked; retry the request"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}
POSTRestore FolderPOSTUnzip File