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

Содержимое корня хранилища

POST /v1/storages/:id/children

Возвращает файлы и папки, лежащие в корне хранилища Битрикс24.Диска. Хранилище адресуется собственным идентификатором, читать его корневую папку заранее не нужно.

Параметры

Параметр Тип Обяз. Описание
Параметрid (path) Типnumber Обяз.да ОписаниеID хранилища. Список хранилищ: GET /v1/storages

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

Поле Тип Обяз. Описание
Полеfilter Типobject Обяз.нет ОписаниеОтбор содержимого корня по точному совпадению. Учитываются пять ключей, записанных прописными буквами: ID, NAME, CODE, TYPE со значением folder или file, STORAGE_ID. Любой другой ключ — в том числе CREATED_BY, UPDATED_BY, SIZE, PARENT_ID — отбрасывается без ошибки, и в ответ приходит всё содержимое корня. Общий синтаксис фильтрации с операторами и camelCase-именами здесь не действует.
Пример: {"filter": {"TYPE": "file"}}
Полеlimit Типinteger Обяз.нет ОписаниеОт 1 до 500 объектов за ответ; по умолчанию 50
Полеoffset Типinteger Обяз.нет ОписаниеНеотрицательное смещение от начала отфильтрованного списка; по умолчанию 0. Сумма offset + limit не должна превышать 9007199254740991

Читайте до meta.hasMore: false. Ответ содержит не больше limit объектов. Для следующей страницы повторите запрос с тем же filter и значением meta.nextOffset в поле offset. meta.total — число объектов после фильтрации. Если содержимое корня меняется между запросами, смещения не образуют снимок: объект может перейти между страницами. Сортировка этой ручкой не принимается. Если Битрикс24 вернул неполный или недостоверный список, API отвечает 502 DISK_READ_UNAVAILABLE, а не выдаёт его за полный.

Когда отбирать нечего, отправляйте {}. Тело обязано быть корректным JSON, а заголовок Content-Type: application/json — стоять.

Примеры

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

Terminal
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://vibecode.bitrix24.tech/v1/storages/11/children

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

Terminal
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://vibecode.bitrix24.tech/v1/storages/11/children

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

javascript
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/storages/11/children',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({}),
  }
)

const body = await res.json()
if (!body.success) throw new Error(body.error.code)

const folders = body.data.filter((item) => item.type === 'folder')
const files = body.data.filter((item) => item.type === 'file')
console.log(`Папок: ${folders.length}, файлов: ${files.length}`)

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

javascript
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/storages/11/children',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({}),
  }
)

const body = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типarray ОписаниеСодержимое корня — папки и файлы вместе. Пустой корень возвращает []
Полеmeta.total Типinteger ОписаниеОбщее число объектов в корне после фильтрации
Полеmeta.limit Типinteger ОписаниеПрименённый предел ответа
Полеmeta.offset Типinteger ОписаниеПрименённое смещение
Полеmeta.hasMore Типboolean Описаниеtrue, если после ответа есть ещё объекты
Полеmeta.nextOffset Типinteger | null ОписаниеСмещение для следующего запроса или null в конце списка
Полеdata[].id Типnumber ОписаниеИдентификатор объекта. У папки по нему читается её содержимое: GET /v1/files?folderId={id}
Полеdata[].name Типstring ОписаниеИмя объекта
Полеdata[].code Типstring | null ОписаниеСимвольный код. null, если не задан
Полеdata[].storageId Типnumber ОписаниеID хранилища. Список хранилищ: GET /v1/storages
Полеdata[].type Типstring ОписаниеТип объекта: "folder" или "file"
Полеdata[].deletedType Типnumber ОписаниеСтатус удаления: 0 — активен, 3 — в корзине, 4 — удалён вместе с папкой
Полеdata[].createdBy Типnumber ОписаниеID создателя. Список сотрудников: GET /v1/users
Полеdata[].updatedBy Типnumber ОписаниеID автора последнего изменения. Список сотрудников: GET /v1/users
Полеdata[].deletedBy Типnumber | null ОписаниеID сотрудника, удалившего объект. Список сотрудников: GET /v1/users. null — не удалён
Полеdata[].createdAt Типdatetime ОписаниеДата создания (ISO 8601)
Полеdata[].updatedAt Типdatetime ОписаниеДата последнего изменения (ISO 8601)
Полеdata[].deletedAt Типdatetime | null ОписаниеДата удаления (ISO 8601). null — не удалён
Полеdata[].detailUrl Типstring ОписаниеСсылка на объект в интерфейсе Битрикс24
Полеdata[].parentId Типnumber ОписаниеID родительской папки. Получить папку: GET /v1/folders/:id. Приходит у записей-папок
Полеdata[].realObjectId Типnumber ОписаниеВнутренний ID объекта. Приходит у записей-папок
Полеdata[].folderId Типnumber ОписаниеID родительской папки. Получить папку: GET /v1/folders/:id. Приходит у записей-файлов
Полеdata[].fileId Типnumber ОписаниеВнутренний ID файла. Приходит у записей-файлов
Полеdata[].size Типnumber ОписаниеРазмер файла в байтах. Приходит у записей-файлов
Полеdata[].globalContentVersion Типnumber ОписаниеСчётчик версий файла. Приходит у записей-файлов
Полеdata[].downloadUrl Типstring ОписаниеАдрес скачивания через API Вайбкод — GET /v1/files/:id/download. Приходит у записей-файлов. Запрос по нему передаёт заголовок X-Api-Key
Полеdata[].contentProvider Типstring ОписаниеПровайдер контента. Возвращается только у файлов из внешних провайдеров контента — у файлов на Диске Битрикс24 не возвращается

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

Показаны две записи из корня — папка и файл.

JSON
{
  "success": true,
  "data": [
    {
      "id": 1925,
      "name": "Договоры",
      "code": null,
      "storageId": 11,
      "type": "folder",
      "realObjectId": 1925,
      "parentId": 19,
      "deletedType": 0,
      "createdAt": "2020-11-20T13:57:37.000Z",
      "updatedAt": "2021-06-29T08:28:49.000Z",
      "deletedAt": null,
      "createdBy": 1,
      "updatedBy": 1,
      "deletedBy": null,
      "detailUrl": "https://example.bitrix24.ru/docs/path/Договоры"
    },
    {
      "id": 117,
      "name": "presentation_q1.pdf",
      "code": null,
      "storageId": 11,
      "type": "file",
      "folderId": 19,
      "deletedType": 0,
      "globalContentVersion": 1,
      "fileId": 253,
      "size": 29887,
      "createdAt": "2020-04-28T06:35:14.000Z",
      "updatedAt": "2020-04-28T06:35:14.000Z",
      "deletedAt": null,
      "createdBy": 1,
      "updatedBy": 1,
      "deletedBy": null,
      "downloadUrl": "https://vibecode.bitrix24.tech/v1/files/117/download",
      "detailUrl": "https://example.bitrix24.ru/docs/file/presentation_q1.pdf"
    }
  ],
  "meta": { "total": 2, "limit": 50, "offset": 0, "hasMore": false, "nextOffset": null }
}

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

404 — хранилища с таким id нет:

JSON
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Could not find entity with id '99999999'."
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_ID Описаниеid в пути не является положительным целым числом
HTTP400 КодINVALID_PARAMS Описаниеlimit не входит в диапазон 1–500, offset отрицательный или их сумма выходит за безопасный диапазон целых чисел
HTTP400 КодFST_ERR_CTP_EMPTY_JSON_BODY ОписаниеЗаголовок Content-Type: application/json стоит, а тело пустое. Отправьте {}
HTTP400 КодFST_ERR_CTP_INVALID_JSON_BODY ОписаниеЗаголовок Content-Type: application/json стоит, а тело не является корректным JSON
HTTP415 КодFST_ERR_CTP_INVALID_MEDIA_TYPE ОписаниеТело отправлено с неподдерживаемым типом содержимого. Так отвечает curl -d без явного заголовка: он по умолчанию ставит application/x-www-form-urlencoded
HTTP401 КодTOKEN_MISSING ОписаниеAPI-ключ не имеет настроенных токенов портала
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа disk
HTTP404 КодENTITY_NOT_FOUND ОписаниеХранилища с указанным id не существует
HTTP429 КодRATE_LIMITED ОписаниеСлишком частые вызовы. Собственного минутного бюджета у операции нет, заголовок x-ratelimit-limit в ответе не приходит — ограничение приходит со стороны Битрикс24. Подождите 1-2 секунды и повторите
HTTP502 КодDISK_READ_UNAVAILABLE ОписаниеБитрикс24 вернул неполную или недостоверную страницу. Повторите чтение позже

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

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

Имя родителя не совпадает с соседним списком. Здесь папка приходит с parentId, а файл с folderId, тогда как список файлов папки отдаёт folderId и папкам тоже. Код, читающий оба списка, должен ветвиться по type.

Недоступное содержимое приходит пустым массивом, а не отказом. Личный диск другого сотрудника отвечает 200 с пустым data — тем же ответом, что и пустой корень. Различить «нет доступа» и «в корне ничего нет» по ответу нельзя.

Операция не входит в пакетные запросы. У хранилищ POST /v1/batch принимает list, search, get и fields — содержимое корня запрашивается отдельным вызовом.

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