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

List folder files

GET /v1/files

Returns a list of objects in the specified folder: folders and files together.

Parameters

Parameter Type Required Default Description
folderId (query) number yes — ID of the folder whose contents to retrieve. Folder list: GET /v1/folders
limit (query) number no 50 Number of records (up to 5000)
offset (query) number no 0 Skip N records
sort (query) string no — Field to sort by
filter (query) object no — Filtering by GET /v1/files/fields fields.
Filtering syntax. Example: ?filter[type]=file

Pagination. With limit > 50 Vibecode automatically runs several requests to Bitrix24 and returns all records in a single response. The maximum is 5000 records per call.

Examples

curl — personal key

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

curl — OAuth app

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

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/files?folderId=27&limit=10', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Objects in folder: ${meta.total}`)

JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/files?folderId=27&limit=10', {
  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 folder objects (folders and files). Full field list of an item — below
data[].id number Object identifier
data[].name string Object name
data[].code string|null Symbolic code; null when unset
data[].storageId number Storage ID. Storage list: GET /v1/storages
data[].type string Type: "file" or "folder"
data[].folderId number Parent folder ID
data[].deletedType number Deletion status: 0 — active, 3 — in trash, 4 — deleted together with the folder
data[].realObjectId number Internal object ID. Present only for folders
data[].createdBy number Creator ID. User list: GET /v1/users
data[].updatedBy number ID of the last editor. User list: GET /v1/users
data[].deletedBy number|null ID of the user who deleted the object; null — not deleted
data[].createdAt datetime Creation date (ISO 8601)
data[].updatedAt datetime Date of the last change (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[].size number File size in bytes. Returned for file records
data[].fileId number Internal file ID. Returned for file records
data[].globalContentVersion number File version counter. Returned for file records
data[].downloadUrl string Temporary download link. Returned for file records. For programmatic download — GET /v1/files/:id/download
data[].contentProvider string Content provider. Returned only for files from external content providers — not returned for files on the Bitrix24 Drive
meta.total number Total number of objects in the folder
meta.hasMore boolean Whether there are more objects beyond limit

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1275,
      "name": "Project archive",
      "code": "ARCHIVE_PROJECT",
      "storageId": 1,
      "type": "folder",
      "folderId": 27,
      "deletedType": 0,
      "realObjectId": 1275,
      "createdBy": 5,
      "updatedBy": 5,
      "deletedBy": null,
      "createdAt": "2023-04-12T08:30:00.000Z",
      "updatedAt": "2023-04-12T08:30:01.000Z",
      "deletedAt": null,
      "detailUrl": "https://example.bitrix24.com/docs/path/to/folder/"
    },
    {
      "id": 205,
      "name": "presentation_q1.pdf",
      "code": null,
      "storageId": 1,
      "type": "file",
      "folderId": 27,
      "size": 31232,
      "fileId": 363,
      "globalContentVersion": 1,
      "downloadUrl": "https://example.bitrix24.com/rest/1/XXXXXX/download/?token=PLACEHOLDER",
      "deletedType": 0,
      "createdBy": 5,
      "updatedBy": 5,
      "deletedBy": null,
      "createdAt": "2023-03-15T09:29:09.000Z",
      "updatedAt": "2023-03-15T09:29:09.000Z",
      "deletedAt": null,
      "detailUrl": "https://example.bitrix24.com/docs/path/to/file/"
    }
  ],
  "meta": { "total": 40, "hasMore": true }
}

Error response example

400 — folderId not provided:

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

Errors

HTTP Code Description
400 MISSING_REQUIRED_PARAMS Required folderId parameter not provided
403 SCOPE_DENIED API key lacks the disk scope
401 TOKEN_MISSING API key has no configured portal tokens
401 INVALID_API_KEY Invalid or expired API key

Full list of common API errors — Error codes.

Known specifics

Mixed list. The response contains both folders (type: "folder") and files (type: "file") at once. Distinguish objects by the type field. The fields size, fileId, globalContentVersion, and downloadUrl are returned for file records. The contentProvider field is not returned for files on the Bitrix24 Drive, and realObjectId only for folders.

See also