## 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 |
|------|-----|:-----:|----------|
| `objectIds` | string[] | yes | Drive file and folder IDs — digit strings, 1 to 50 IDs without duplicates. Search: [`POST /v1/disk/search`](/docs/disk/search), the `data.items[].objectId` field. Folder contents: [`GET /v1/files?folderId=…`](/docs/entities/files/list) |
| `sections` | string[] | no | Visibility check sections: `metadata`, `location`, `access`, `relations`. 1 to 4 values without duplicates |

## Examples

### curl — personal key

```bash
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

```bash
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 |
|------|-----|----------|
| `success` | boolean | `true` on a successful check |
| `data.items` | array | Result for each ID — in the same order as in `objectIds` |
| `data.items[].objectId` | string | Object ID from the request |
| `data.items[].visible` | boolean | `true` — the user currently sees the object, `false` — does not |
| `data.items[].card` | object | Current object card. Absent when `visible` is `false` or the current object data could not be retrieved |
| `data.items[].card.objectId` | string | Object ID |
| `data.items[].card.objectType` | string | Object type: `file` or `folder` |
| `data.items[].card.name` | string | File or folder name |
| `data.items[].card.storageId` | string | Storage ID. List: [`GET /v1/storages`](/docs/entities/storages/list) |
| `data.items[].card.parentId` | string | Parent folder ID. Folder: [`GET /v1/folders/:id`](/docs/entities/folders/get) |
| `data.items[].card.size` | string | File size in bytes, as a digit string. Files only |
| `data.items[].card.contentFileId` | string | ID of the current file content. Files only |
| `data.items[].card.contentGeneration` | string | File content version counter, as a digit string. Files only |
| `data.items[].card.versionId` | string | ID of the current file version. Not returned on every Bitrix24 account |
| `data.items[].card.versionNumber` | string | Number of the current file version, as a digit string. Not returned on every Bitrix24 account |
| `data.items[].card.contentAvailable` | boolean | Whether the file content is available. Not returned on every Bitrix24 account |
| `data.items[].card.safeLink` | string | HTTPS link to the object in the Bitrix24 web interface |
| `data.items[].card.source` | string | Card 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 |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | The 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 |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |
| 401 | `INVALID_API_KEY` | The key was not recognized |
| 401 | `TOKEN_MISSING` | The key has no portal tokens configured |
| 401 | `DISK_AUTH_UNAVAILABLE` | The 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 |
| 401 | `TOKEN_REFRESH_FAILED` | The portal authorization for the key could not be refreshed. Retrying will not help until the key is authorized again |
| 403 | `SCOPE_DENIED` | The key lacks the `disk` scope |
| 403 | `DISK_ACCESS_DENIED` | The portal denied access to the visibility check |
| 502 | `DISK_READ_UNAVAILABLE` | At 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 |
| 502 | `DISK_UNSUPPORTED` | The portal returned the check result in a format that could not be parsed |
| 503 | `QUERY_LIMIT_EXCEEDED` | The portal rejected the call because the request limit was exceeded |
| 503 | `BITRIX_TIMEOUT` | The portal did not respond within the allotted time |
| 503 | `QUEUE_OVERFLOW`, `QUEUE_TIMEOUT` | The portal request queue is full. The `Retry-After` header gives the pause before retrying |
| 503 | `RATE_LIMITED` | The portal responded with HTTP 429. The `Retry-After` header gives the pause before retrying |
| 503 | `ERROR_LOOP_DETECTED` | Repeated errors from this key on this method have temporarily blocked calls. The `Retry-After` header gives the pause |
| 503 | `user_self_deletion_pending` | The key owner is awaiting account deletion on the portal. Access returns once the deletion is cancelled |

Full list of common API errors — [Errors](/docs/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`](/docs/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

- [Get Drive capabilities](/docs/disk/capabilities)
- [Search Drive](/docs/disk/search)
- [Folder file list](/docs/entities/files/list)
- [Get a folder](/docs/entities/folders/get)
- [Errors](/docs/errors)