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
parentId (query) number yes ID of the folder whose contents are listed. The storage root folder is the rootFolderId field in GET /v1/storages
filter (query) object no Filtering by GET /v1/folders/fields fields.
Filtering syntax. Example: ?filter[type]=folder
select (query) string no all fields Comma-separated list of returned fields. Example: ?select=id,name
order (query) object no Sorting by field. Example: ?order[name]=asc
limit (query) number no 50 How many records to return. Maximum 5000
offset (query) number no 0 Offset for paginated selection
include (query) string no Load 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 the 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 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 app

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 app

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
success boolean Always true on success
data array Array of records — subfolders (type: "folder") and files (type: "file"). All fields — see Folder fields
data[].type string Record type: "folder" or "file". Distinguishes two row schemas in one array
meta.total number Total number of records in the folder
meta.hasMore boolean Whether there are more records beyond limit

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 account 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://<portal>.bitrix24.com/rest/1/****/download/?token=****"
    }
  ],
  "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
400 MISSING_REQUIRED_PARAMS Required parentId not provided
400 INVALID_INCLUDE The include value is not supported. The available value is storage
403 SCOPE_DENIED The API key does not have the disk scope
401 TOKEN_MISSING The API key has no configured portal tokens

Full list of general API errors — 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