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

List folder contents

GET /v1/folders

Returns the contents of a folder — nested subfolders and files. The parentId parameter is required — without it the request returns 400.

Parameters

Parameter Type Required Default Description
ParameterparentId (query) Typenumber Requiredyes Default DescriptionID of the folder whose contents are listed. The storage root folder is the rootFolderId field in GET /v1/storages
Parameterfilter (query) Typeobject Requiredno Default DescriptionFiltering only by the fields Bitrix24 can filter by: id, name, code, storageId, type, parentId, deletedType, createdAt, updatedAt, deletedAt. The remaining fields of GET /v1/folders/fields (for example createdBy, updatedBy) cannot be filtered — such a request returns 400 UNSUPPORTED_FILTER listing the allowed ones. Operators ($gt, $contains, and the rest) are not supported: exact match and $in only.
Filtering syntax. Example: ?filter[type]=folder
Parameterselect (query) Typestring Requiredno Defaultall fields DescriptionComma-separated list of returned fields. Example: ?select=id,name
Parametersort (query) Typestring Requiredno Default DescriptionSorting in short syntax. A leading minus means descending. Separate several fields with commas. Example: ?sort=-createdAt
Parameterorder (query) Typeobject Requiredno Default DescriptionSorting in object form. Example: ?order[name]=asc
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionHow many records to return. Maximum 5000
Parameteroffset (query) Typenumber Requiredno Default0 DescriptionOffset for pagination
Parameterinclude (query) Typestring Requiredno Default DescriptionLoad a related object for every record. The available value is storage. The result arrives in the _included block. For a selection of more than 200 records, relations are not loaded and meta.includeSkipped returns true

For limit > 50 Vibecode automatically paginates the request on the server side. The maximum is 5000 records per call. If more records match the filter, meta.hasMore returns true.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/folders?parentId=27&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/folders?parentId=27&limit=10" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const params = new URLSearchParams({ parentId: '27', limit: '10' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/folders?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log('Records:', data.length, 'total:', meta.total)

JavaScript — OAuth application

javascript 
const params = new URLSearchParams({ parentId: '27', limit: '10' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/folders?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of records — subfolders (type: "folder") and files (type: "file"). All fields — see Folder fields
Fielddata[].type Typestring DescriptionRecord type: "folder" or "file". Distinguishes two row schemas in one array
Fieldmeta.total Typenumber DescriptionTotal number of records in the folder
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit
Fieldmeta.includeSkipped Typeboolean Descriptiontrue if the response holds more than 200 records and the relations from include are not loaded. Reduce limit. With 200 records or fewer, the field is absent

File records carry their own field set — fileId, size, globalContentVersion, downloadUrl, folderId — and do not contain realObjectId. File management is in the Files section.

The detailUrl field is the full URL of the folder card in Bitrix24, for example https://<portal>.bitrix24.com/company/personal/user/1/disk/path/<name>/. <portal> is the Bitrix24 portal domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 9301,
      "name": "Documents",
      "code": null,
      "storageId": 1,
      "type": "folder",
      "realObjectId": 9301,
      "parentId": 27,
      "deletedType": 0,
      "createdAt": "2026-06-25T12:10:00.000Z",
      "updatedAt": "2026-06-25T12:10:00.000Z",
      "deletedAt": null,
      "createdBy": 1,
      "updatedBy": 1,
      "deletedBy": null,
      "detailUrl": "https://<portal>.bitrix24.com/company/personal/user/1/disk/path/Documents"
    },
    {
      "id": 205,
      "name": "report.pdf",
      "code": null,
      "storageId": 1,
      "type": "file",
      "folderId": 27,
      "deletedType": 0,
      "globalContentVersion": 1,
      "fileId": 363,
      "size": 31232,
      "createdAt": "2020-05-15T09:29:09.000Z",
      "updatedAt": "2020-05-15T09:29:09.000Z",
      "deletedAt": null,
      "createdBy": 1,
      "updatedBy": 1,
      "deletedBy": null,
      "downloadUrl": "https://vibecode.bitrix24.com/v1/files/205/download"
    }
  ],
  "meta": { "total": 22, "hasMore": false }
}

With the include=storage parameter an _included block is added to every record. The main record fields are shown:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 9301,
      "name": "Documents",
      "storageId": 1,
      "type": "folder",
      "parentId": 27,
      "_included": {
        "storage": {
          "id": 1,
          "name": "John Smith",
          "code": null,
          "module": "disk",
          "entityType": "user",
          "entityId": "1",
          "rootFolderId": 1
        }
      }
    }
  ],
  "meta": { "total": 22, "hasMore": false }
}

Error response example

400 — required parentId not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "GET /v1/folders requires query parameters: parentId. Example: GET /v1/folders?parentId=..."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_PARAMS DescriptionRequired parentId not provided
HTTP400 CodeINVALID_INCLUDE DescriptionThe include value is not supported. The available value is storage
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the disk scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured portal tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of general API errors, see Errors.

Known specifics

GET /v1/folders lists the children of a single folder specified via parentId. This is not a flat list of all folders in the storage — to traverse the tree, request each folder separately by its id. The storage root folder is given by the rootFolderId field in GET /v1/storages.

See also