For AI agents: markdown of this page — /docs-content-en/entities/files/fulltext-search.md documentation index — /llms.txt

Full-text Disk search

POST /v1/files/fulltext-search

Searches the index across all accessible Disk storage. Single-folder search accepts filters, while this route accepts a search string. Requires the disk scope. READONLY keys are allowed.

Request fields

Field Type Required Description
Fieldquery Typestring Requiredyes DescriptionRequired. Whitespace is collapsed and trimmed, then length must be 3..255 characters
Fieldtype Typestring Requiredno Descriptionfile, folder, all. Default file
Fieldfilter.storageId Typenumber Requiredno DescriptionPositive integer ID from the storage list
Fieldfilter.folderId Typenumber Requiredno DescriptionPositive integer ID from the folder list
Fieldfilter.fileType Typestring or array Requiredno DescriptionOnly with type=file: document, image, video, audio, archive, pdf, vector_image, board, known, unknown. An array must not be empty
Fieldoffset Typenumber Requiredno DescriptionInteger 0..1000, default 0

Unknown fields are rejected. limit is not accepted: the native Bitrix24 page size is fixed at 50 records.

Examples

curl — personal key

Terminal 
curl -X POST 'https://vibecode.bitrix24.com/v1/files/fulltext-search' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"query":"report","filter":{"fileType":"document"},"offset":0}'

curl — OAuth application

Terminal 
curl -X POST 'https://vibecode.bitrix24.com/v1/files/fulltext-search' \
  -H 'X-Api-Key: YOUR_APP_KEY' \
  -H 'Authorization: Bearer USER_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"query":"report","filter":{"fileType":"document"},"offset":0}'

JavaScript — personal key

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/files/fulltext-search', {
  method: 'POST',
  headers: {"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({"query": "report", "filter": {"fileType": "document"}, "offset": 0}),
})
const result = await response.json()
console.log(result)

JavaScript — OAuth application

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/files/fulltext-search', {
  method: 'POST',
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({"query": "report", "filter": {"fileType": "document"}, "offset": 0}),
})
const result = await response.json()
console.log(result)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionWhether the request succeeded
Fielddata Typeobject DescriptionSearch result: the items array and the meta pagination parameters
Fielddata.items Typearray DescriptionFiles and folders — fields as in Get file and Get a folder
Fielddata.meta.nextOffset Typenumber | null DescriptionNext offset. null at the end of the results
Fielddata.meta.maxOffset Typenumber DescriptionMaximum offset: 1000

data.items contains files in the files projection and folders in the folders projection. Call downloadUrl with the same API key. data.meta.nextOffset is the next page offset or null; use it in the next request. There is no total: Bitrix24 does not return the match count.

Trash is excluded. Empty results do not prove that a file is absent: the index updates asynchronously, and not every format has its content indexed. Searching by name is more reliable. You cannot continue past offset 1000; narrow the query.

Response example

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 10639,
        "name": "report.txt",
        "code": null,
        "storageId": 1,
        "type": "file",
        "folderId": 27,
        "deletedType": 0,
        "globalContentVersion": 1,
        "fileId": 39127,
        "size": 11,
        "createdAt": "2026-10-13T11:15:36.000Z",
        "updatedAt": "2026-10-13T11:15:36.000Z",
        "deletedAt": null,
        "createdBy": 1,
        "updatedBy": 1,
        "deletedBy": null,
        "downloadUrl": "https://vibecode.bitrix24.com/v1/files/10639/download",
        "detailUrl": "https://example.bitrix24.com/company/personal/user/1/disk/file/report.txt"
      }
    ],
    "meta": {
      "nextOffset": null,
      "maxOffset": 1000
    }
  }
}

Error response example

400 — query is shorter than three characters:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "query must contain 3..255 characters after whitespace normalization."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid query, type, filter or offset, unknown fields
HTTP403 CodeSCOPE_DENIED DescriptionMissing disk scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access
HTTP404 CodeENTITY_NOT_FOUND DescriptionStorage or folder not found or inaccessible. These causes are intentionally indistinguishable
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 business refusal or response without a result
HTTP422 CodeOPERATION_FAILED DescriptionBitrix24 business refusal or response without a result

Common refusals: Errors.

See also