> ## Documentation Index > Fetch the complete documentation index at: https://botpress-pb-update-api.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # searchFiles > Search files ## OpenAPI ````yaml /files-openapi.json get /v1/files/search openapi: 3.0.0 info: title: Botpress Files API description: API for Botpress Files version: 1.112.0 servers: - url: https://api.botpress.cloud security: - BearerAuth: [] tags: - name: documented paths: /v1/files/search: get: tags: - Endpoints description: Search files operationId: searchFiles parameters: - name: tags in: query description: >- Filter files by tags. Tags should be passed as a URL-encoded JSON object of key-value pairs that must be present in the tags of a file. An array of multiple string values for the same key are treated as an OR condition. To exclude a value, express it as an object with a nested `not` key with the string or string-array value(s) to exclude. schema: {} - name: query in: query description: >- Query expressed in natural language to retrieve matching text passages within all indexed files in the bot using semantical search. required: true schema: type: string - name: contextDepth in: query description: >- The number of neighbor passages to prepend and append as surrounding context to the content of each returned passage (default: 1, minimum: 0, maximum: 10). schema: type: integer - name: limit in: query description: The maximum number of passages to return. schema: type: integer - name: consolidate in: query description: >- Consolidate the results by merging matching passages from the same file into a single passage per file. The consolidated passage will include the matching passages ordered by their original position in the file (rather than by relevance score) and include hierarchical context such as the title/subtitle to which they belong. schema: type: boolean - name: includeBreadcrumb in: query description: >- Prepend a breadcrumb to each passage, containing the title and subtitle(s) the passage belongs to in the file. This option is ignored when the `consolidate` option is set to `true`. schema: type: boolean - name: withContext in: query description: >- Include the surrounding context with each passage in the `context` property of each passage. Not supported when `consolidate` is set to `true`. schema: type: boolean - name: x-bot-id in: header description: Bot id required: true schema: type: string - name: x-integration-id in: header description: Integration id required: false schema: type: string - name: x-integration-alias in: header description: Integration alias required: false schema: type: string - name: x-integration-name in: header description: Integration name required: false schema: type: string - name: x-user-id in: header description: User Id required: false schema: type: string - name: x-user-role in: header description: User Role required: false schema: type: string responses: '200': $ref: '#/components/responses/searchFilesResponse' default: $ref: '#/components/responses/searchFilesResponse' components: responses: searchFilesResponse: description: >- Returns the text passages within all indexed files that matched the query. content: application/json: schema: type: object properties: passages: type: array items: type: object properties: content: type: string description: >- The content of the matching passage in the file including surrounding context, if any. score: type: number description: >- The score indicating the similarity of the passage to the query. A higher score indicates higher similarity. meta: type: object properties: type: type: string enum: - chunk - summary - consolidated - image description: The type of passage subtype: type: string enum: - title - subtitle - paragraph - blockquote - list - table - code - image - page description: The subtype of passage, if available. pageNumber: type: integer description: >- Page number the passage is located on. Only applicable if the passage was extracted from a PDF file. position: type: integer description: >- Position number of the passage in the file relative to the other passages, if available. Can be used to know the order of passages within a file. sourceUrl: type: string format: uri description: >- The URL of the source file for the vector, if applicable (e.g. for image vectors). description: The passage metadata. file: type: object properties: id: type: string description: File ID key: type: string description: >- Unique key for the file. Must be unique across the bot (and the integration, when applicable). contentType: type: string description: MIME type of the file's content metadata: type: object additionalProperties: nullable: true description: >- Metadata of the file as an object of key-value pairs. tags: type: object additionalProperties: type: string maxLength: 1000 description: >- The tags of the file as an object of key-value pairs. createdAt: type: string description: File creation timestamp in ISO 8601 format updatedAt: type: string description: File last update timestamp in ISO 8601 format required: - id - key - contentType - metadata - tags - createdAt - updatedAt context: type: array items: type: object properties: id: type: string format: uuid description: >- The ID of the vector that the context passage belongs to. Omitted for breadcrumbs. text: type: string offset: type: integer description: >- Position of the context passage relative to the current passage. Negative for preceding passages, positive for subsequent, ommited for breadcrumbs. type: type: string enum: - preceding - subsequent - current - breadcrumb description: The type of context passage required: - text - type description: >- Surrounding passages including the current passage, based on the requested `contextDepth`. Only returned if the `withContext` parameter is set to `true`. Not supported when using the `consolidate` option. required: - content - score - meta - file required: - passages title: searchFilesResponse additionalProperties: false securitySchemes: BearerAuth: type: http scheme: bearer ````