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

`POST /v1/storages/:id/children`

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

## Параметры

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

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

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|---------|
| `filter` | object | нет | Отбор содержимого корня по точному совпадению. Учитываются пять ключей, записанных прописными буквами: `ID`, `NAME`, `CODE`, `TYPE` со значением `folder` или `file`, `STORAGE_ID`. Любой другой ключ — в том числе `CREATED_BY`, `UPDATED_BY`, `SIZE`, `PARENT_ID` — отбрасывается без ошибки, и в ответ приходит всё содержимое корня. Общий [синтаксис фильтрации](/docs/filtering) с операторами и camelCase-именами здесь не действует.<br>Пример: `{"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 — личный ключ

```bash
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-приложение

```bash
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}`](/docs/entities/files/list) |
| `data[].name` | string | Имя объекта |
| `data[].code` | string \| null | Символьный код. `null`, если не задан |
| `data[].storageId` | number | ID хранилища. Список хранилищ: [`GET /v1/storages`](./list.md) |
| `data[].type` | string | Тип объекта: `"folder"` или `"file"` |
| `data[].deletedType` | number | Статус удаления: `0` — активен, `3` — в корзине, `4` — удалён вместе с папкой |
| `data[].createdBy` | number | ID создателя. Список сотрудников: [`GET /v1/users`](/docs/entities/users) |
| `data[].updatedBy` | number | ID автора последнего изменения. Список сотрудников: [`GET /v1/users`](/docs/entities/users) |
| `data[].deletedBy` | number \| null | ID сотрудника, удалившего объект. Список сотрудников: [`GET /v1/users`](/docs/entities/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`](/docs/entities/folders/get). Приходит у записей-папок |
| `data[].realObjectId` | number | Внутренний ID объекта. Приходит у записей-папок |
| `data[].folderId` | number | ID родительской папки. Получить папку: [`GET /v1/folders/:id`](/docs/entities/folders/get). Приходит у записей-файлов |
| `data[].fileId` | number | Внутренний ID файла. Приходит у записей-файлов |
| `data[].size` | number | Размер файла в байтах. Приходит у записей-файлов |
| `data[].globalContentVersion` | number | Счётчик версий файла. Приходит у записей-файлов |
| `data[].downloadUrl` | string | Адрес скачивания через API Вайбкод — [`GET /v1/files/:id/download`](/docs/entities/files/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 | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_ID` | `id` в пути не является положительным целым числом |
| 400 | `INVALID_PARAMS` | `limit` не входит в диапазон 1–500, `offset` отрицательный или их сумма выходит за безопасный диапазон целых чисел |
| 400 | `FST_ERR_CTP_EMPTY_JSON_BODY` | Заголовок `Content-Type: application/json` стоит, а тело пустое. Отправьте `{}` |
| 400 | `FST_ERR_CTP_INVALID_JSON_BODY` | Заголовок `Content-Type: application/json` стоит, а тело не является корректным JSON |
| 415 | `FST_ERR_CTP_INVALID_MEDIA_TYPE` | Тело отправлено с неподдерживаемым типом содержимого. Так отвечает `curl -d` без явного заголовка: он по умолчанию ставит `application/x-www-form-urlencoded` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов портала |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `disk` |
| 404 | `ENTITY_NOT_FOUND` | Хранилища с указанным `id` не существует |
| 429 | `RATE_LIMITED` | Слишком частые вызовы. Собственного минутного бюджета у операции нет, заголовок `x-ratelimit-limit` в ответе не приходит — ограничение приходит со стороны Битрикс24. Подождите 1-2 секунды и повторите |
| 502 | `DISK_READ_UNAVAILABLE` | Битрикс24 вернул неполную или недостоверную страницу. Повторите чтение позже |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

**Имя родителя не совпадает с соседним списком.** Здесь папка приходит с `parentId`, а файл с `folderId`, тогда как [список файлов папки](/docs/entities/files/list) отдаёт `folderId` и папкам тоже. Код, читающий оба списка, должен ветвиться по `type`.

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

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

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

- [Список хранилищ](/docs/entities/storages/list)
- [Получить хранилище](/docs/entities/storages/get)
- [Хранилища](/docs/entities/storages)
- [Список файлов](/docs/entities/files/list)
- [Папки](/docs/entities/folders)
