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, auto-pagination when limit > 50.

Result ordering. With no sort the list arrives ascending by id. id is appended to your sort as a final key, so the order is always total and unambiguous and paging over it is repeatable: when sorting by a non-unique field, a row sharing that value could otherwise land on two pages at once, or drop out, at a page boundary. If you sort by id yourself, your direction is preserved.

Request fields (body)

Parameter Type Default Description
filter object — Exact equality and $in (IN set) only, over the 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: increase offset by the size of the batch you received until meta.hasMore turns false
select string[] — Field selection: ["id", "name"]. Only the listed fields are returned
sort string — Sort field, a leading minus means descending: "-id". The fields that change the order are id, name, entityType, entityId, rootFolderId (verified live). The method also accepts code and module, but on the accounts we checked those fields hold the same value for every storage, so ordering by them changes nothing
order object — The same in object form: { "id": "desc" }. When both are passed, sort wins

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 Whether there are more records beyond limit
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
403 SCOPE_DENIED The API key does not have the disk scope
401 TOKEN_MISSING The API key has no configured tokens
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

See also