Para agentes de IA: markdown desta página — /docs-content-en/entities/files.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

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
folderId (query) number yes — ID of the folder whose contents are returned. 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 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
success boolean Always true on success
data array Array of objects in the folder (folders and files). Full list of item fields — 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
429 RATE_LIMITED Rate 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