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
Parameterfilter Typeobject Default— DescriptionExact 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" }
Parameterlimit Typenumber Default50 DescriptionNumber of records (up to 5000). When limit > 50 the request is assembled automatically from several pages on the server side
Parameteroffset Typenumber Default0 DescriptionSkip 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
Parameterselect Typestring[] Default— DescriptionField selection: ["id", "name"]. Only the listed fields are returned
Parametersort Typestring Default— DescriptionSort 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
Parameterorder Typeobject Default— DescriptionThe 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of storages (see Storage fields)
Fieldmeta.total Typenumber DescriptionTotal number of records matching the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds

The meta fields sit next to data, not inside it. Page through the results using 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
HTTP400 CodeUNSUPPORTED_FILTER DescriptionOperator or unsupported field in the filter. Filter by exact equality or $in on id, name, code, entityType, entityId
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the disk scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

See also