> ## Documentation Index > Fetch the complete documentation index at: https://docs.stefanbrain.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Follow the content contract in AGENTS.md. > Treat text as the canonical explanation; video and screenshots enhance it. > Do not publish unverified product behavior or duplicate an existing canonical article. # Search a chat's workspace files by name and contents > The chat's current workspace files whose name or words match `q`, name matches first, then the best content matches; each content match carries up to two passages around the words it matched. `q` reads like a web search ("quoted phrases", or, -word) and its last word matches as a prefix. Answers come from a search index: a new file matches by name at once and by its words about a minute after it is written. Searches what GET /files lists, less StefanBrain's scratch (frames, temporary folders, logs); a typed output (an image set, video cuts, a report) answers once, as the file in it that matched best. ## OpenAPI ````yaml /developers/openapi/stefanbrain-v1.json get /api/developers/v1/files/search openapi: 3.1.0 info: title: StefanBrain Developer API version: 1.0.0 description: >- REST access to StefanBrain agent runs, tools, and jobs. Authenticate with an API key from Settings → Developers. REST usage bills your prepaid API wallet at the published per-token rates (see https://docs.stefanbrain.com/developers/pricing); the MCP endpoint (/api/developers/v1/mcp, not described here) is member pricing from your plan pool. Human documentation: https://docs.stefanbrain.com/developers servers: - url: https://stefanbrain.com security: - bearerAuth: [] - apiKeyHeader: [] tags: - name: tools description: Directly invocable StefanBrain tools. - name: jobs description: Long-running tool jobs (poll for results). - name: runs description: Agentic chat runs with event streams. - name: files description: Workspace files agent runs produced in a chat. - name: media description: 'Stored Meta ad media facts: video transcripts on demand.' - name: feedback description: >- Tell StefanBrain where the API got in your way, and read the team's replies. - name: meta description: 'Meta landing page labels: the label lists, and the one checked write.' paths: /api/developers/v1/files/search: get: tags: - files summary: Search a chat's workspace files by name and contents description: >- The chat's current workspace files whose name or words match `q`, name matches first, then the best content matches; each content match carries up to two passages around the words it matched. `q` reads like a web search ("quoted phrases", or, -word) and its last word matches as a prefix. Answers come from a search index: a new file matches by name at once and by its words about a minute after it is written. Searches what GET /files lists, less StefanBrain's scratch (frames, temporary folders, logs); a typed output (an image set, video cuts, a report) answers once, as the file in it that matched best. operationId: searchFiles parameters: - name: chat_id in: query required: true description: The chat whose files to search (a chat UUID or chat_... id). schema: type: string - name: q in: query required: true description: 'What to find: words of a file''s name or contents.' schema: type: string minLength: 1 maxLength: 200 responses: '200': description: Up to 50 matches, one per file or typed output. content: application/json: schema: $ref: '#/components/schemas/WorkspaceFileSearch' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Suspended key, missing plan access, or key scoped away from this surface (code api_key_scope_forbidden). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Chat not found for this account. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Rate limited (codes request_per_minute, request_per_minute_user, request_per_day, user_throttled, user_suspended; Retry-After header when the limit has a reset time, plus limits, observed counts, and reset_at in the body), the runtime has no capacity to start a turn right now (code runtime_capacity_busy, Retry-After: 5), wallet exhausted (code api_wallet_exhausted), key budget exhausted (code api_key_budget_exhausted), or the plan's monthly usage pool spent for OAuth-token traffic (code monthly_usage_limit_reached). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: WorkspaceFileSearch: type: object properties: object: type: string const: workspace_file_search chat: type: string results: type: array items: $ref: '#/components/schemas/WorkspaceFileSearchResult' additionalProperties: true Error: type: object required: - error properties: error: type: object required: - message - type properties: message: type: string type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - api_error - service_unavailable_error code: type: string additionalProperties: true additionalProperties: true WorkspaceFileSearchResult: type: object properties: object: type: string const: workspace_file_search_result id: type: string pattern: ^[0-9a-f]{64}$ description: 'The SHA-256 of the file''s current content: its GET /files id.' path: type: string description: Logical workspace path. file_name: type: string name: type: - string - 'null' description: The member's name for the file, when they renamed it. kind: type: string enum: - output - upload media_type: type: string size_bytes: type: integer updated_at: type: string format: date-time match: type: string enum: - name - content description: Whether the file matched by its name (ranked first) or by its words. snippets: type: array description: >- Up to two passages around a content match, each a run of parts; `match` marks a matched word. items: type: array items: type: object properties: text: type: string match: type: boolean required: - text - match additionalProperties: true securitySchemes: bearerAuth: type: http scheme: bearer description: >- Authorization: Bearer stefan_sk_... (API key — bills the API wallet) or stefan_oat_... (OAuth member token — bills your plan pool). apiKeyHeader: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.