Skip to main content
GET
/
v1
/
files
/
search
cURL
curl --request GET \
  --url https://api.botpress.cloud/v1/files/search \
  --header 'Authorization: Bearer <token>' \
  --header 'x-bot-id: <x-bot-id>'
{
  "passages": [
    {
      "content": "<string>",
      "score": 123,
      "meta": {
        "type": "chunk",
        "subtype": "title",
        "pageNumber": 123,
        "position": 123,
        "sourceUrl": "<string>"
      },
      "file": {
        "id": "<string>",
        "key": "<string>",
        "contentType": "<string>",
        "metadata": {},
        "tags": {},
        "createdAt": "<string>",
        "updatedAt": "<string>"
      },
      "context": [
        {
          "text": "<string>",
          "type": "preceding",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "offset": 123
        }
      ]
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-bot-id
string
required

Bot id

​
x-integration-id
string

Integration id

​
x-integration-alias
string

Integration alias

​
x-integration-name
string

Integration name

​
x-user-id
string

User Id

​
x-user-role
string

User Role

Query Parameters

​
query
string
required

Query expressed in natural language to retrieve matching text passages within all indexed files in the bot using semantical search.

​
contextDepth
integer

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).

​
limit
integer

The maximum number of passages to return.

​
consolidate
boolean

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.

​
includeBreadcrumb
boolean

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.

​
withContext
boolean

Include the surrounding context with each passage in the context property of each passage. Not supported when consolidate is set to true.

Response

Returns the text passages within all indexed files that matched the query.

​
passages
object[]
required
Last modified on November 13, 2025