## Contents of the storage root `POST /v1/storages/:id/children` Returns the files and folders located in the root of a Bitrix24 Drive storage. The storage is addressed by its own identifier, so you do not need to read its root folder first. ## Parameters | Parameter | Type | Required | Description | |----------|-----|:-----:|---------| | `id` (path) | number | yes | Storage ID. List of storages: [`GET /v1/storages`](./list.md) | ## Request fields (body) | Field | Type | Required | Description | |------|-----|:-----:|---------| | `filter` | object | no | Filters the root contents by exact match. Five upper-case keys are honoured: `ID`, `NAME`, `CODE`, `TYPE` with the value `folder` or `file`, `STORAGE_ID`. Any other key — including `CREATED_BY`, `UPDATED_BY`, `SIZE`, `PARENT_ID` — is discarded without an error, and the entire root contents are returned. The general [filtering syntax](/docs/filtering) with operators and camelCase names does not apply here.
Example: `{"filter": {"TYPE": "file"}}` | **The response is capped at one Bitrix24 page.** Only the `filter` key is read from the request body — `limit`, `offset` and sorting values are not accepted, and the response carries no `meta` block. A root holding more objects than fit on one page returns that page alone, and nothing in the response flags the truncation: no total count, no continuation flag, no cursor. A partial response is indistinguishable from a complete one, so narrow a large root with `filter` and read nested folders one at a time through [`GET /v1/files?folderId={id}`](/docs/entities/files/list), which does support pagination. **When there is nothing to filter by, send `{}`.** The body must be valid JSON and the `Content-Type: application/json` header must be present. ## Examples ### curl — personal key ```bash curl -X POST \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' \ https://vibecode.bitrix24.com/v1/storages/11/children ``` ### curl — OAuth application ```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.com/v1/storages/11/children ``` ### JavaScript — personal key ```javascript const res = await fetch( 'https://vibecode.bitrix24.com/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: ${folders.length}, files: ${files.length}`) ``` ### JavaScript — OAuth application ```javascript const res = await fetch( 'https://vibecode.bitrix24.com/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() ``` ## Response fields | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data` | array | The root contents — folders and files together. An empty root returns `[]` | | `data[].id` | number | Object identifier. For a folder, use it to read the folder contents: [`GET /v1/files?folderId={id}`](/docs/entities/files/list) | | `data[].name` | string | Object name | | `data[].code` | string \| null | Symbolic code. `null` when not set | | `data[].storageId` | number | Storage ID. List of storages: [`GET /v1/storages`](./list.md) | | `data[].type` | string | Object type: `"folder"` or `"file"` | | `data[].deletedType` | number | Deletion status: `0` — active, `3` — in the recycle bin, `4` — deleted together with the folder | | `data[].createdBy` | number | Creator ID. Employee list: [`GET /v1/users`](/docs/entities/users) | | `data[].updatedBy` | number | ID of the last editor. Employee list: [`GET /v1/users`](/docs/entities/users) | | `data[].deletedBy` | number \| null | ID of the employee who deleted the object. Employee list: [`GET /v1/users`](/docs/entities/users). `null` — not deleted | | `data[].createdAt` | datetime | Creation date (ISO 8601) | | `data[].updatedAt` | datetime | Last modification date (ISO 8601) | | `data[].deletedAt` | datetime \| null | Deletion date (ISO 8601). `null` — not deleted | | `data[].detailUrl` | string | Link to the object in the Bitrix24 interface | | `data[].parentId` | number | Parent folder ID. Fetch the folder: [`GET /v1/folders/:id`](/docs/entities/folders/get). Returned for folder records | | `data[].realObjectId` | number | Internal object ID. Returned for folder records | | `data[].folderId` | number | Parent folder ID. Fetch the folder: [`GET /v1/folders/:id`](/docs/entities/folders/get). Returned for file records | | `data[].fileId` | number | Internal file ID. Returned for file records | | `data[].size` | number | File size in bytes. Returned for file records | | `data[].globalContentVersion` | number | File version counter. Returned for file records | | `data[].downloadUrl` | string | Vibecode API download address — [`GET /v1/files/:id/download`](/docs/entities/files/download). Returned for file records; send the `X-Api-Key` header when you follow it | | `data[].contentProvider` | string | Content provider. Returned only for files from external content providers — not returned for files on Bitrix24 Drive | ## Response example Two records from the root are shown — a folder and a file. ```json { "success": true, "data": [ { "id": 1925, "name": "Contracts", "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.com/docs/path/Contracts" }, { "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.com/v1/files/117/download", "detailUrl": "https://example.bitrix24.com/docs/file/presentation_q1.pdf" } ] } ``` ## Error response example 404 — there is no storage with this `id`: ```json { "success": false, "error": { "code": "ENTITY_NOT_FOUND", "message": "Could not find entity with id '99999999'." } } ``` ## Errors | HTTP | Code | Description | |------|-----|---------| | 400 | `INVALID_ID` | The `id` in the path is not a positive integer | | 400 | `FST_ERR_CTP_EMPTY_JSON_BODY` | The `Content-Type: application/json` header is set but the body is empty. Send `{}` | | 400 | `FST_ERR_CTP_INVALID_JSON_BODY` | The `Content-Type: application/json` header is set but the body is not valid JSON | | 415 | `FST_ERR_CTP_INVALID_MEDIA_TYPE` | The body was sent with an unsupported content type. That is what `curl -d` without an explicit header produces: it defaults to `application/x-www-form-urlencoded` | | 401 | `TOKEN_MISSING` | The API key has no configured portal tokens | | 403 | `SCOPE_DENIED` | The API key does not have the `disk` scope | | 404 | `ENTITY_NOT_FOUND` | No storage with the given `id` exists | | 429 | `RATE_LIMITED` | Calls are coming in too fast. The operation has no per-minute budget of its own and the response carries no `x-ratelimit-limit` header — the limit comes from the Bitrix24 side. Wait 1-2 seconds and retry | The full list of common API errors — [Errors](/docs/errors). ## Known specifics **The parent field name does not match the neighbouring list.** Here a folder arrives with `parentId` and a file with `folderId`, whereas [List folder files](/docs/entities/files/list) returns `folderId` for folders as well. Code that reads both listings has to branch on `type`. **Inaccessible contents arrive as an empty array rather than an error.** Another employee's personal drive answers `200` with an empty `data` — the same response as an empty root. Nothing in the response distinguishes "no access" from "the root is empty". **The operation is not available in batch requests.** For storages [`POST /v1/batch`](/docs/batch) accepts `list`, `search`, `get` and `fields` — the root contents are requested by a separate call. ## See also - [List storages](/docs/entities/storages/list) - [Get a storage](/docs/entities/storages/get) - [Storages](/docs/entities/storages) - [List folder files](/docs/entities/files/list) - [Folders](/docs/entities/folders)