"> "> ">

Для AI-агентов: markdown этой страницы — /docs-content/entities/storages/search.md индекс документации — /llms.txt

Поиск хранилищ

POST /v1/storages/search

Поиск хранилищ с фильтрами. Аналог GET /v1/storages с фильтром, но через POST — условия по нескольким полям передаются в теле запроса. Фильтрация по точному совпадению полей, автопагинация при limit > 50.

Порядок выдачи. Без сортировки список приходит по возрастанию id. К вашей сортировке id добавляется последним ключом, поэтому порядок всегда полный и однозначный, а постраничный обход повторяем: при сортировке по неуникальному полю строка с тем же значением иначе могла на границе страниц попасть в две страницы сразу или пропасть. Если вы сортируете по id сами, ваше направление сохраняется.

Поля запроса (body)

Параметр Тип По умолч. Описание
filter object — Только точное равенство и $in (IN-множество) по полям id, name, code, entityType, entityId. Операторы (>, >=, <, <=, !, %, $ne, $contains, $nin) и другие поля (например rootFolderId) не поддерживаются — вернётся 400 UNSUPPORTED_FILTER.
Синтаксис фильтрации. Пример: { "entityType": "group" }
limit number 50 Количество записей (до 5000). При limit > 50 запрос автоматически собирается из нескольких страниц на стороне сервера
offset number 0 Пропустить N записей. Применяется для чтения выборок больше 5000 записей
select string[] — Выборка полей: ["id", "name"]. Возвращаются только перечисленные поля
sort string — Поле сортировки, минус впереди означает по убыванию: "-id". Порядок меняют id, name, entityType, entityId, rootFolderId (проверено живьём). Поля code и module метод принимает, но на проверенных аккаунтах эти колонки одинаковы у всех хранилищ, поэтому порядок по ним не меняется
order object — То же в объектной форме: { "id": "desc" }. При одновременной передаче с sort выигрывает sort

Примеры

curl — личный ключ

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

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/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 — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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(`Всего хранилищ под фильтром: ${meta.total}`)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив хранилищ (см. Поля хранилища)
meta.total number Общее количество записей, соответствующих фильтру
meta.hasMore boolean Есть ли ещё записи за пределами limit
meta.durationMs number Длительность запроса в миллисекундах

Поля meta лежат рядом с data, а не внутри него. Обходить страницы нужно по meta.hasMore: длина data, равная limit, последней страницы не исключает.

Пример ответа

JSON 
{
  "success": true,
  "data": [
    {
      "id": 3,
      "name": "Закрытая видимая группа",
      "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
  }
}

Пример ответа при ошибке

400 — оператор или неподдерживаемое поле в фильтре:

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."
  }
}

Ошибки

HTTP Код Описание
400 UNSUPPORTED_FILTER Оператор или неподдерживаемое поле в фильтре. Фильтруйте точным равенством или $in по id, name, code, entityType, entityId
403 SCOPE_DENIED API-ключ не имеет скоупа disk
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Выборки больше 5000 записей. За один ответ возвращается до 5000 хранилищ. Общее число записей под фильтром приходит в meta.total, признак наличия продолжения — в meta.hasMore. Если под фильтр попадает больше 5000 записей, читайте продолжение параметром offset, увеличивая его на размер полученной порции.

Смотрите также