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

Get Drive capabilities

GET /v1/disk/capabilities

Reports which Drive agent operations are available to this key on the Bitrix24 account: search, sync, and file saving. Call it first, before search, upload, and sync.

Parameters

There are no parameters. No request body is sent.

Examples

curl — personal key

Terminal 
curl https://vibecode.bitrix24.com/v1/disk/capabilities \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/disk/capabilities \
  -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/disk/capabilities', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
if (!data.sync.available) {
  console.log('Sync is not available on this Bitrix24 account:', data.reason)
}
console.log('Search:', data.search.available, 'Upload:', data.save.create)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/disk/capabilities', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Search:', data.search.available, 'Sync:', data.sync.available)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful response
Fielddata.contractVersion Typenumber DescriptionDrive agent contract version. Currently always 1
Fielddata.identity.scopeRef Typestring DescriptionOpaque binding identifier: the Bitrix24 account, the Bitrix24 user, and the key or application making the call. Computed by the server, not taken from the request
Fielddata.identity.portalId Typestring DescriptionBitrix24 portal ID on the Vibecode platform
Fielddata.identity.nativeUserId Typestring DescriptionID of the Bitrix24 user on whose behalf calls run. Employee list: GET /v1/users
Fielddata.identity.accountGeneration Typestring DescriptionBinding generation. Grows when the binding credentials change. After it grows, previously issued search cursors and sync descriptors are not accepted
Fielddata.search.available Typeboolean DescriptionWhether Drive search is available on the Bitrix24 account
Fielddata.search.filters Typestring[] DescriptionSearch filter fields: storageId, folderId, fileType
Fielddata.search.types Typestring[] DescriptionValues of the search type field: file, folder, all
Fielddata.search.queryMin Typenumber DescriptionMinimum search string length, 3
Fielddata.search.queryMax Typenumber DescriptionMaximum search string length, 255
Fielddata.sync.available Typeboolean DescriptionWhether sync is available. With false, the sync object contains only three fields: available, statusAvailable, retryAvailable
Fielddata.sync.statusAvailable Typeboolean DescriptionWhether sync status is available. Equals data.sync.available
Fielddata.sync.retryAvailable Typeboolean DescriptionWhether a sync retry is available. Equals data.sync.available
Fielddata.sync.schemaVersion Typenumber DescriptionOnly with available: true. Sync schema version of the Bitrix24 account: 1 or 2
Fielddata.sync.cardSections Typeobject DescriptionOnly with available: true. Which object card sections the Bitrix24 account returns: metadata, location, access, relations, each flagged true or false
Fielddata.sync.changeTypes Typestring[] DescriptionOnly with available: true. Change types in the journal: update, tombstone, accessChanged, indexUpdated
Fielddata.sync.limits.pageSizeMax Typenumber DescriptionOnly with available: true. Maximum objects per sync page
Fielddata.sync.limits.pageSizeMaxHeavy Typenumber DescriptionOnly with available: true. Maximum objects per page when the location, access, or relations sections are requested
Fielddata.sync.limits.checkBatchMax Typenumber DescriptionOnly with available: true. Maximum objects in a visibility check inside a sync session when only the metadata section is requested, equal to pageSizeMax. With the location, access, or relations sections, including the default ones, pageSizeMaxHeavy applies. A visibility check by an objectIds list outside sync accepts 1 to 50 IDs whatever this field reports. May be absent
Fielddata.sync.retention.journalRetentionDays Typenumber DescriptionOnly with available: true. How many days the Bitrix24 account keeps the change journal
Fielddata.sync.retention.interactionWindowDays Typenumber DescriptionOnly with available: true. Depth of the user's file activity history, in days
Fielddata.sync.retention.safeWindowSeconds Typenumber DescriptionOnly with available: true. Change journal consistency window in seconds, as reported by the Bitrix24 account
Fielddata.sync.pollBounds.minSeconds Typenumber DescriptionOnly with available: true. Minimum change polling interval in seconds
Fielddata.sync.pollBounds.recommendedSeconds Typenumber DescriptionOnly with available: true. Recommended polling interval in seconds
Fielddata.sync.pollBounds.maxSeconds Typenumber DescriptionOnly with available: true. Maximum polling interval in seconds
Fielddata.sync.executionBudgetMs Typenumber DescriptionOnly with available: true. How many milliseconds one sync attempt is allotted. The platform sets the value; a request cannot change it
Fielddata.save.create Typeboolean DescriptionWhether a new file can be uploaded
Fielddata.save.version Typeboolean DescriptionWhether a new version of an existing file can be uploaded
Fielddata.save.reserveAvailable Typeboolean DescriptionWhether an upload can be reserved. true if create or version is available
Fielddata.save.maxBytes Typenumber DescriptionMaximum upload file size in bytes: 26214400, 25 MiB
Fielddata.save.atomicConcurrency Typeboolean DescriptionAlways false: the file version check before uploading a new version is not atomic, so a concurrent change between the check and the write is possible
Fielddata.reason Typestring DescriptionWhy sync or search is unavailable: DISK_UNSUPPORTED means the Bitrix24 account does not support the capability, DISK_ACCESS_DENIED means Bitrix24 denied the user access to sync. Absent when everything is available

Response example

Search and saving are available, sync is not available on this Bitrix24 account:

JSON 
{
  "success": true,
  "data": {
    "contractVersion": 1,
    "identity": {
      "scopeRef": "7073c6856e1b4dde1e1dca88006d87684a3219c7f7becb059abba0989f257e0b",
      "portalId": "0d9f7744-f853-47c7-b06e-6f61f9dd1b7f",
      "nativeUserId": "1",
      "accountGeneration": "1"
    },
    "search": {
      "available": true,
      "filters": ["storageId", "folderId", "fileType"],
      "types": ["file", "folder", "all"],
      "queryMin": 3,
      "queryMax": 255
    },
    "sync": {
      "available": false,
      "statusAvailable": false,
      "retryAvailable": false
    },
    "save": {
      "create": true,
      "version": true,
      "reserveAvailable": true,
      "maxBytes": 26214400,
      "atomicConcurrency": false
    },
    "reason": "DISK_UNSUPPORTED"
  }
}

Error response example

401: the X-Api-Key header is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

The envelope of the Drive agent's own errors is described in Error codes.

Errors

HTTP Code Description
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no authorization configured on the Bitrix24 portal
HTTP401 CodeDISK_AUTH_UNAVAILABLE DescriptionThe Bitrix24 user could not be confirmed: the key's webhook does not match the Bitrix24 portal or user, an OAuth application key was sent without Authorization: Bearer, the session token belongs to another application or portal, or the Bitrix24 token has expired or been revoked
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized
HTTP401 CodeTOKEN_REFRESH_FAILED DescriptionFailed to refresh the Bitrix24 portal authorization for the key. Retrying will not help until the key is authorized again
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the disk scope
HTTP403 CodeDISK_ACCESS_DENIED DescriptionBitrix24 denied the user access while reading capabilities
HTTP501 CodeDISK_UNSUPPORTED DescriptionThe Bitrix24 portal did not return the list of available methods in the expected form
HTTP502 CodeDISK_READ_UNAVAILABLE DescriptionThe read failed for a reason not covered by the other codes. Retry the request later
HTTP503 CodeQUERY_LIMIT_EXCEEDED DescriptionThe Bitrix24 portal throttled the request rate
HTTP503 CodeBITRIX_TIMEOUT DescriptionThe Bitrix24 portal did not respond in time
HTTP503 CodeQUEUE_OVERFLOW, QUEUE_TIMEOUT DescriptionThe Bitrix24 portal call queue is full. The Retry-After header gives the delay before retrying
HTTP503 Codeuser_self_deletion_pending DescriptionThe key owner requested deletion of their account, so Drive calls are stopped
HTTP503 CodeRATE_LIMITED DescriptionThe Bitrix24 portal responded with HTTP 429. The Retry-After header gives the delay before retrying
HTTP503 CodeERROR_LOOP_DETECTED DescriptionRepeated errors from this key on this method temporarily stopped calls. The Retry-After header gives the delay

Full list of common API errors: Errors.

Known specifics

Unavailable sync does not affect the rest. With sync.available: false, search, file upload, and visibility checks on an objectIds list still work.

Read-only key. For a key with the read-only access mode, the save.create, save.version, and save.reserveAvailable fields are false on any Bitrix24 account, and upload responds with 403 WRITE_BLOCKED_READONLY. Search and reading capabilities work with such a key.

Flags describe the Bitrix24 account, not a guarantee. The response is built from the list of methods the Bitrix24 account returns to this user, so the flags can change after a Bitrix24 update or a permission change, with nothing changed on the application side. Limits and retention periods in data.sync are values observed on the Bitrix24 account, not a promise of complete results.

See also