For AI agents: markdown of this page — /docs-content-en/entities/storages/children.md documentation index — /llms.txt

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

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 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}, 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

Terminal 
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

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.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}
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
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
data[].updatedBy number ID of the last editor. Employee list: GET /v1/users
data[].deletedBy number | null ID of the employee who deleted the object. Employee list: GET /v1/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. 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. 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. 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.

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 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 accepts list, search, get and fields — the root contents are requested by a separate call.

See also