"> "> ">

Для 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 записей: увеличивайте offset на размер полученной порции, пока meta.hasMore не станет false
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-ключ не имеет настроенных токенов
429 RATE_LIMITED Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики). Повторите после срока из заголовка Retry-After

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

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