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

Files

Manage files on the Bitrix24 Drive: list, upload, download, rename, move, copy, and delete. Files are stored in folders inside storages.

Bitrix24 API: disk.file.* Scope: disk

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
ParameterfolderId (query) Typenumber Requiredyes Default— DescriptionID of the folder whose contents are returned. Folder list: GET /v1/folders
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionNumber of records (up to 5000)
Parameteroffset (query) Typenumber Requiredno Default0 DescriptionSkip N records
Parametersort (query) Typestring Requiredno Default— DescriptionField to sort by
Parameterorder (query) Typeobject | string Requiredno Default— DescriptionTwo forms. The object form, ?order[name]=desc, applies only when sort is not passed: the direction is asc or desc, and any other value returns 400 INVALID_SORT_DIRECTION. The string form, ?order=desc, switches the sort fields to descending and has no effect without sort
Parameterselect (query) Typestring Requiredno Defaultall fields DescriptionComma-separated list of returned fields. Example: ?select=id,name. Names come from GET /v1/files/fields
Parameterinclude (query) Typestring Requiredno Default— DescriptionLoad the folder that contains each record. The available value is folder. The result arrives in the _included field of every record
ParameterwithTotal (query) Typestring Requiredno Default— DescriptionAccepted, but does not change the response: meta.total is returned for any value of the parameter and at any offset
Parameterfilter (query) Typeobject Requiredno Default— DescriptionFiltering only by the fields Bitrix24 can filter by: id, name, code, storageId, type, folderId, deletedType, createdAt, updatedAt, deletedAt. The other fields returned by GET /v1/files/fields (for example createdBy, size, updatedBy) cannot be filtered — such a request returns 400 UNSUPPORTED_FILTER listing the allowed ones. Operators ($gt, $contains, and others) are not supported: exact match and $in only.
Filtering syntax. Example: ?filter[type]=file

Pagination. When limit > 50, Vibecode automatically makes 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 application

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 application

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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of objects in the folder (folders and files). The full list of item fields is below
Fielddata[].id Typenumber DescriptionObject identifier
Fielddata[].name Typestring DescriptionObject name
Fielddata[].code Typestring|null DescriptionSymbolic code; null when unset
Fielddata[].storageId Typenumber DescriptionStorage ID. Storage list: GET /v1/storages
Fielddata[].type Typestring DescriptionType: "file" or "folder"
Fielddata[].folderId Typenumber DescriptionParent folder ID
Fielddata[].deletedType Typenumber DescriptionDeletion status: 0 — active, 3 — in trash, 4 — deleted together with the folder
Fielddata[].realObjectId Typenumber DescriptionInternal object ID. Present only for folders
Fielddata[].createdBy Typenumber DescriptionCreator ID. User list: GET /v1/users
Fielddata[].updatedBy Typenumber DescriptionID of the last editor. User list: GET /v1/users
Fielddata[].deletedBy Typenumber|null DescriptionID of the user who deleted the object; null — not deleted
Fielddata[].createdAt Typedatetime DescriptionCreation date (ISO 8601)
Fielddata[].updatedAt Typedatetime DescriptionDate of the last change (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[].size Typenumber DescriptionFile size in bytes. Returned for file records
Fielddata[].fileId Typenumber DescriptionInternal file ID. 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
Fieldmeta.total Typenumber DescriptionTotal number of objects in the folder
Fieldmeta.hasMore Typeboolean DescriptionWhether 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://vibecode.bitrix24.com/v1/files/205/download",
      "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
HTTP400 CodeMISSING_REQUIRED_PARAMS DescriptionRequired folderId parameter not provided
HTTP400 CodeUNKNOWN_SELECT_FIELD Descriptionselect contains an unknown field. The message lists the allowed names
HTTP400 CodeINVALID_INCLUDE DescriptionThe include value is not supported. The available value is folder
HTTP400 CodeINVALID_SORT_DIRECTION DescriptionThe object form of order contains a direction other than asc or desc
HTTP403 CodeSCOPE_DENIED DescriptionAPI key lacks the disk scope
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured portal tokens
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
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 common API errors, see Errors.

See also