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
Parameterid (path) Typenumber Requiredyes DescriptionStorage ID. List of storages: GET /v1/storages

Request fields (body)

Field Type Required Description
Fieldfilter Typeobject Requiredno DescriptionFilters 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"}}
Fieldlimit Typeinteger Requiredno DescriptionFrom 1 to 500 objects per response; default 50
Fieldoffset Typeinteger Requiredno DescriptionNonnegative row offset in the filtered list; default 0. offset + limit must not exceed 9007199254740991

Read until meta.hasMore is false. The response contains at most limit objects. For the next page, repeat the same filter and put meta.nextOffset in the offset field. meta.total counts the filtered root. Offset pages are not a snapshot: changes to the root between requests can move objects between pages. This route does not accept sorting. If Bitrix24 returns an incomplete or unverifiable list, the API returns 502 DISK_READ_UNAVAILABLE instead of presenting it as complete.

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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionThe root contents — folders and files together. An empty root returns []
Fieldmeta.total Typeinteger DescriptionTotal number of filtered root objects
Fieldmeta.limit Typeinteger DescriptionApplied response limit
Fieldmeta.offset Typeinteger DescriptionApplied row offset
Fieldmeta.hasMore Typeboolean Descriptiontrue when more objects remain after this page
Fieldmeta.nextOffset Typeinteger | null DescriptionOffset for the next request, or null at the end
Fielddata[].id Typenumber DescriptionObject identifier. For a folder, use it to read the folder contents: GET /v1/files?folderId={id}
Fielddata[].name Typestring DescriptionObject name
Fielddata[].code Typestring | null DescriptionSymbolic code. null when not set
Fielddata[].storageId Typenumber DescriptionStorage ID. List of storages: GET /v1/storages
Fielddata[].type Typestring DescriptionObject type: "folder" or "file"
Fielddata[].deletedType Typenumber DescriptionDeletion status: 0 — active, 3 — in the recycle bin, 4 — deleted together with the folder
Fielddata[].createdBy Typenumber DescriptionCreator ID. Employee list: GET /v1/users
Fielddata[].updatedBy Typenumber DescriptionID of the last editor. Employee list: GET /v1/users
Fielddata[].deletedBy Typenumber | null DescriptionID of the employee who deleted the object. Employee list: GET /v1/users. null — not deleted
Fielddata[].createdAt Typedatetime DescriptionCreation date (ISO 8601)
Fielddata[].updatedAt Typedatetime DescriptionLast modification date (ISO 8601)
Fielddata[].deletedAt Typedatetime | null DescriptionDeletion date (ISO 8601). null — not deleted
Fielddata[].detailUrl Typestring DescriptionLink to the object in the Bitrix24 interface
Fielddata[].parentId Typenumber DescriptionParent folder ID. Fetch the folder: GET /v1/folders/:id. Returned for folder records
Fielddata[].realObjectId Typenumber DescriptionInternal object ID. Returned for folder records
Fielddata[].folderId Typenumber DescriptionParent folder ID. Fetch the folder: GET /v1/folders/:id. Returned for file records
Fielddata[].fileId Typenumber DescriptionInternal file ID. Returned for file records
Fielddata[].size Typenumber DescriptionFile size in bytes. Returned for file records
Fielddata[].globalContentVersion Typenumber DescriptionFile version counter. Returned for file records
Fielddata[].downloadUrl Typestring DescriptionVibecode API download address — GET /v1/files/:id/download. Returned for file records; send the X-Api-Key header when you follow it
Fielddata[].contentProvider Typestring DescriptionContent 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"
    }
  ],
  "meta": { "total": 2, "limit": 50, "offset": 0, "hasMore": false, "nextOffset": null }
}

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
HTTP400 CodeINVALID_ID DescriptionThe id in the path is not a positive integer
HTTP400 CodeINVALID_PARAMS Descriptionlimit is outside 1–500, offset is negative, or their sum exceeds the safe integer range
HTTP400 CodeFST_ERR_CTP_EMPTY_JSON_BODY DescriptionThe Content-Type: application/json header is set but the body is empty. Send {}
HTTP400 CodeFST_ERR_CTP_INVALID_JSON_BODY DescriptionThe Content-Type: application/json header is set but the body is not valid JSON
HTTP415 CodeFST_ERR_CTP_INVALID_MEDIA_TYPE DescriptionThe 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
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured portal tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the disk scope
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo storage with the given id exists
HTTP429 CodeRATE_LIMITED DescriptionCalls 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
HTTP502 CodeDISK_READ_UNAVAILABLE DescriptionBitrix24 returned an incomplete or unverifiable page. Retry the read later

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