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

Search storages

POST /v1/storages/search

Search storages with filters. Equivalent to GET /v1/storages with a filter, but via POST — conditions across several fields are passed in the request body. Filtering by exact field match, autopagination when limit > 50.

Request fields (body)

Parameter Type Default Description
filter object — Exact equality and $in (IN set) only, on fields id, name, code, entityType, entityId. Operators (>, >=, <, <=, !, %, $ne, $contains, $nin) and other fields (for example rootFolderId) are not supported — returns 400 UNSUPPORTED_FILTER.
Filtering syntax. Example: { "entityType": "group" }
limit number 50 Number of records (up to 5000). When limit > 50 the request is assembled automatically from several pages on the server side
offset number 0 Skip N records. Used to read result sets larger than 5000 records
select string[] — Field selection: ["id", "name"]. Only the listed fields are returned

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/storages/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityType": "group" },
    "limit": 10
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/storages/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityType": "group" },
    "limit": 10
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/storages/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { entityType: 'group' },
    limit: 10,
  }),
})

const { success, data, meta } = await res.json()
console.log(`Total storages matching the filter: ${meta.total}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/storages/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { entityType: 'group' },
    limit: 10,
  }),
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array Array of storages (see Storage fields)
meta.total number Total number of records matching the filter
meta.hasMore boolean Indicates whether additional records exist
meta.durationMs number Request duration in milliseconds

The meta fields sit next to data, not inside it. Pages must be walked by meta.hasMore: a data length equal to limit does not rule out the last page.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 3,
      "name": "Private visible group",
      "code": null,
      "module": "disk",
      "entityType": "group",
      "entityId": "1",
      "rootFolderId": 3
    },
    {
      "id": 113,
      "name": "test111",
      "code": null,
      "module": "disk",
      "entityType": "group",
      "entityId": "11",
      "rootFolderId": 787
    }
  ],
  "meta": {
    "total": 38,
    "hasMore": true,
    "durationMs": 150
  }
}

Error response example

400 — operator or unsupported field in the filter:

JSON 
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILTER",
    "message": "UNSUPPORTED_FILTER: operators are not supported on 'storages' (near 'id'). Its Bitrix24 method (disk.storage.getlist) filters by exact match only — operators are silently ignored by Bitrix24. Use exact match (field: value) or $in (field: {$in: [...]}) on: id, name, code, entityType, entityId."
  }
}

Errors

HTTP Code Description
400 UNSUPPORTED_FILTER Operator or unsupported field in the filter. Filter by exact equality or $in on id, name, code, entityType, entityId
400 INVALID_SORT_FIELD The body contains sort or order — storages do not support sorting
403 SCOPE_DENIED The API key does not have the disk scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Result sets larger than 5000 records. A single response returns up to 5000 storages. The total number of records under the filter comes in meta.total, and whether a continuation exists comes in meta.hasMore. If more than 5000 records match the filter, read the continuation with the offset parameter, increasing it by the size of the received batch.

See also