> ## Documentation Index > Fetch the complete documentation index at: https://docs.replicas.dev/llms.txt > Use this file to discover all available pages before exploring further. # Search Workspace Files > Lists repository file paths without waking the workspace. Requires a logged-in user JWT and Replicas-Org-Id. Workspace indexes are cached for seven days; active workspaces serve cached results immediately and refresh indexes older than 30 seconds in the background. Without a saved index, inactive workspaces use GitHub/GitLab default-branch trees cached for five minutes. Fallbacks may omit workspace-only files. Failed refreshes or mixed engine page versions preserve the last complete index. Follow nextCursor until null; if indexedAt changes, discard accumulated pages and restart without refresh. Poll only while refreshing is true. File contents still require the engine. ## OpenAPI ````yaml /openapi.json get /v1/workspaces/{workspaceId}/repo-files/search openapi: 3.1.0 info: title: Replica API version: 2.0.0 description: >- The Replica API allows you to programmatically manage cloud workspaces for AI agents. Use this API to manage environments (the org-scoped primitive workspaces are created from — including variables, files, skills, MCPs, warm hooks, start hooks, and warm pools), create and manage replicas, send messages, manage chats, stream events, read connected repositories and repository sets, and configure automations. servers: - url: https://api.replicas.dev description: Production API security: - apiKey: [] tags: - name: Environments description: >- Manage environments — the primitive that workspaces are created from. Variables, files, skills, MCPs, warm-hooks, and warm-pools are all scoped to an environment. Every organization has a singleton Global environment whose values apply to every workspace. Personal environments are scoped to the authenticated user and can be standalone or source-backed by a team environment. - name: Repository description: >- Read repositories and repository sets connected to your organization. Repositories are the underlying GitHub-connection layer; bind them to an environment to use them in workspaces. - name: Replica description: >- Manage replicas (workspaces) for AI agents. Workspace creation with `POST /v1/replica` accepts API keys and workspace engine-secret authentication. Other Replica operations also accept logged-in user JWTs from first-party clients. - name: Terminal description: Manage interactive terminal sessions in active workspaces - name: Tunnels description: Create short-lived authenticated transports to active workspaces - name: Preview description: Manage public preview URLs for workspace ports - name: Profile description: Read and update the authenticated user's profile - name: Credentials description: >- Manage coding-agent credentials for an organization or the authenticated user - name: Preferences description: Manage organization behavior preferences - name: Organization roles description: >- Manage custom roles and member role assignments. Organization admins retain full access independently of custom roles. - name: Organization invitations description: Manage pending organization invitations - name: Onboarding description: Read and update first-party organization onboarding progress - name: Slack description: Connect Slack identities and route threads to Replicas workspaces - name: Linear description: Connect Linear identities to Replicas accounts - name: Sentry description: Manage the organization's Sentry connection - name: Automation description: >- Create and manage automations that trigger replicas on a schedule or in response to events - name: Downloads description: Download Replicas applications - name: Media description: >- Read workspace media and obtain short-lived download or inline preview URLs - name: Analytics description: >- Read aggregated activity and usage metrics for your organization: compute minutes, workspaces created by source, and pull request throughput over a time range. - name: Presence description: >- Read and report ephemeral member presence: who is online, where they are (environment or workspace), and whether they are typing. Presence is backed by short-lived keys rather than the database and broadcast to other members over the events stream. - name: Plugins description: >- Install and manage native and Composio-backed workspace plugins. A plugin installs for a single environment, for the whole organization (which uses the Global environment), or for one member personally. A workspace uses the most specific installation available: personal, then its own environment, then the environment it was branched from, then Global. Composio Connect Links host managed OAuth, custom OAuth, API-key, bearer-token, basic, and dynamic OAuth authentication without exposing provider credentials to Replicas. paths: /v1/workspaces/{workspaceId}/repo-files/search: get: tags: - Replica summary: Search Workspace Files description: >- Lists repository file paths without waking the workspace. Requires a logged-in user JWT and Replicas-Org-Id. Workspace indexes are cached for seven days; active workspaces serve cached results immediately and refresh indexes older than 30 seconds in the background. Without a saved index, inactive workspaces use GitHub/GitLab default-branch trees cached for five minutes. Fallbacks may omit workspace-only files. Failed refreshes or mixed engine page versions preserve the last complete index. Follow nextCursor until null; if indexedAt changes, discard accumulated pages and restart without refresh. Poll only while refreshing is true. File contents still require the engine. operationId: searchWorkspaceRepoFiles parameters: - name: workspaceId in: path required: true schema: type: string format: uuid - name: Replicas-Org-Id in: header required: true description: Organization UUID containing the workspace. schema: type: string format: uuid - name: q in: query description: Filename or path search; empty lists all indexed files. schema: type: string default: '' - name: prefix in: query description: >- Restrict results to repository-relative paths starting with this prefix. schema: type: string default: '' - name: limit in: query description: Page size. Out-of-range integers are clamped to 1–5,000. schema: type: integer minimum: 1 maximum: 5000 default: 50 - name: cursor in: query description: >- Opaque nextCursor from the previous page. Keep q, prefix, and limit unchanged. schema: type: string - name: refresh in: query description: >- On the first page, true waits for an active engine refresh. Does not wake inactive workspaces. On failure, a saved index or repository fallback may still be returned as stale. schema: type: boolean default: false responses: '200': description: Live, cached, or repository-fallback file paths. content: application/json: schema: $ref: '#/components/schemas/SearchRepoFilesResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: Organization access denied. '404': $ref: '#/components/responses/NotFound' '503': description: No usable workspace or repository index is available. content: application/json: schema: type: object required: - error properties: error: type: string security: - userJwt: [] components: schemas: SearchRepoFilesResponse: type: object required: - files - nextCursor - indexedAt - stale properties: files: type: array items: $ref: '#/components/schemas/RepoFileEntry' nextCursor: type: - string - 'null' description: Opaque cursor for the next page; null when pagination is complete. indexedAt: type: string format: date-time description: >- Index version. Discard accumulated pages and restart without refresh if this value changes between pages. stale: type: boolean description: >- Results are cached or from a repository fallback and may not reflect the current workspace. Does not by itself mean a refresh is pending. refreshing: type: boolean description: >- A background workspace index refresh is pending. Poll only while true; inactive fallback results do not enable polling. truncated: type: boolean description: >- Index is incomplete due to provider limits, index caps, or unavailable repositories; independent of nextCursor. unsupported: type: boolean description: >- Optional compatibility flag indicating repository file search is unsupported. RepoFileEntry: type: object required: - repoName - path - displayPath - status - score - indexedAt - stale properties: repoName: type: string path: type: string description: Path relative to the repository root. displayPath: type: string description: Repository-qualified path for multi-repository workspaces. status: type: string enum: - changed - untouched score: type: number description: >- Search relevance score; results sort by descending score, then displayPath. indexedAt: type: string format: date-time stale: type: boolean Error: type: object properties: error: type: string description: Error message details: type: - string - 'null' description: Additional error details code: type: string description: Machine-readable error code when available required: - error responses: BadRequest: description: Bad request - Missing or invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: http scheme: bearer description: >- API key authentication. Obtain your API key from the Replicas dashboard under Organization → Settings → API Keys. userJwt: type: http scheme: bearer description: >- Logged-in user-session JWT authentication for first-party clients. Org-scoped requests also require the `Replicas-Org-Id` header. User JWTs cannot create workspaces with `POST /v1/replica`. ````