لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/files.md فهرس التوثيق — /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
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). Full list of item fields — 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 the 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
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 exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

See also