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

Check Drive object visibility

POST /v1/disk/sync/check

Checks whether the Bitrix24 user the key acts on behalf of currently sees the specified Drive files and folders, and returns their current cards. The method also works on a Bitrix24 account where Drive sync is unavailable.

Request fields (body)

Field Type Required Description
FieldobjectIds Typestring[] Requiredyes DescriptionDrive file and folder IDs — digit strings, 1 to 50 IDs without duplicates. Search: POST /v1/disk/search, the data.items[].objectId field. Folder contents: GET /v1/files?folderId=…
Fieldsections Typestring[] Requiredno DescriptionVisibility check sections: metadata, location, access, relations. 1 to 4 values without duplicates

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/disk/sync/check \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objectIds": ["10899", "9987"]
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/disk/sync/check \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "objectIds": ["10899", "9987"]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/disk/sync/check', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    objectIds: ['10899', '9987'],
  }),
})

const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
for (const item of data.items) {
  console.log(item.objectId, item.visible, item.card?.name)
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/disk/sync/check', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    objectIds: ['10899', '9987'],
  }),
})

const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
for (const item of data.items) {
  console.log(item.objectId, item.visible, item.card?.name)
}

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful check
Fielddata.items Typearray DescriptionResult for each ID — in the same order as in objectIds
Fielddata.items[].objectId Typestring DescriptionObject ID from the request
Fielddata.items[].visible Typeboolean Descriptiontrue — the user currently sees the object, false — does not
Fielddata.items[].card Typeobject DescriptionCurrent object card. Absent when visible is false or the current object data could not be retrieved
Fielddata.items[].card.objectId Typestring DescriptionObject ID
Fielddata.items[].card.objectType Typestring DescriptionObject type: file or folder
Fielddata.items[].card.name Typestring DescriptionFile or folder name
Fielddata.items[].card.storageId Typestring DescriptionStorage ID. List: GET /v1/storages
Fielddata.items[].card.parentId Typestring DescriptionParent folder ID. Folder: GET /v1/folders/:id
Fielddata.items[].card.size Typestring DescriptionFile size in bytes, as a digit string. Files only
Fielddata.items[].card.contentFileId Typestring DescriptionID of the current file content. Files only
Fielddata.items[].card.contentGeneration Typestring DescriptionFile content version counter, as a digit string. Files only
Fielddata.items[].card.versionId Typestring DescriptionID of the current file version. Not returned on every Bitrix24 account
Fielddata.items[].card.versionNumber Typestring DescriptionNumber of the current file version, as a digit string. Not returned on every Bitrix24 account
Fielddata.items[].card.contentAvailable Typeboolean DescriptionWhether the file content is available. Not returned on every Bitrix24 account
Fielddata.items[].card.safeLink Typestring DescriptionHTTPS link to the object in the Bitrix24 web interface
Fielddata.items[].card.source Typestring DescriptionCard origin. native-current — the card is built from the current object data at the time of the request

Response example

A file and a folder the user sees:

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "objectId": "10899",
        "visible": true,
        "card": {
          "objectId": "10899",
          "objectType": "file",
          "name": "vibe-disk-docs-check.txt",
          "storageId": "1",
          "parentId": "1",
          "size": "27",
          "contentFileId": "39553",
          "contentGeneration": "1",
          "safeLink": "https://example.bitrix24.com/company/personal/user/1/disk/file/vibe-disk-docs-check.txt",
          "source": "native-current"
        }
      },
      {
        "objectId": "9987",
        "visible": true,
        "card": {
          "objectId": "9987",
          "objectType": "folder",
          "name": "2026-08",
          "storageId": "11",
          "parentId": "9075",
          "safeLink": "https://example.bitrix24.com/docs/path/Reports/2026-08",
          "source": "native-current"
        }
      }
    ]
  }
}

Error response example

400 — empty objectIds array:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Disk request unavailable",
    "retrySafe": false
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe body failed validation: empty objectIds, more than 50 IDs, duplicate IDs, an ID that is not a digit string, an unknown or duplicate value in sections, an extra field in the body
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe key was not recognized
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no portal tokens configured
HTTP401 CodeDISK_AUTH_UNAVAILABLE DescriptionThe Bitrix24 user the key acts on behalf of could not be confirmed: for an application key the session token in Authorization: Bearer is missing or invalid, the key's inbound webhook was issued to a different user, the key works through personal OAuth authorization, or the portal rejected the token as expired
HTTP401 CodeTOKEN_REFRESH_FAILED DescriptionThe portal authorization for the key could not be refreshed. Retrying will not help until the key is authorized again
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the disk scope
HTTP403 CodeDISK_ACCESS_DENIED DescriptionThe portal denied access to the visibility check
HTTP502 CodeDISK_READ_UNAVAILABLE DescriptionAt least one object from objectIds could not be read: no such ID, the user has no access to it, or the object is in the Recycle Bin. The refusal applies to the whole request
HTTP502 CodeDISK_UNSUPPORTED DescriptionThe portal returned the check result in a format that could not be parsed
HTTP503 CodeQUERY_LIMIT_EXCEEDED DescriptionThe portal rejected the call because the request limit was exceeded
HTTP503 CodeBITRIX_TIMEOUT DescriptionThe portal did not respond within the allotted time
HTTP503 CodeQUEUE_OVERFLOW, QUEUE_TIMEOUT DescriptionThe portal request queue is full. The Retry-After header gives the pause before retrying
HTTP503 CodeRATE_LIMITED DescriptionThe portal responded with HTTP 429. The Retry-After header gives the pause before retrying
HTTP503 CodeERROR_LOOP_DETECTED DescriptionRepeated errors from this key on this method have temporarily blocked calls. The Retry-After header gives the pause
HTTP503 Codeuser_self_deletion_pending DescriptionThe key owner is awaiting account deletion on the portal. Access returns once the deletion is cancelled

Full list of common API errors — Errors.

Known specifics

  • Check an unreadable ID one at a time. On a Bitrix24 account where Drive sync is unavailable, every object in the response arrives with visible: true and a card, and there is no partial result. To find the ID that caused the request to be rejected, check the objects one at a time. The sync availability flag is the sync.available field in GET /v1/disk/capabilities.
  • The card's field set does not depend on sections. The card is built from the current object data the same way for any sections value.
  • retrySafe does not suggest a retry. For this method's errors, error.retrySafe is always false. Base the retry decision on the error code and the Retry-After header.

See also