## 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

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

### curl — OAuth application

```bash
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 |
|------|-----|----------|
| `success` | boolean | `true` on a successful response |
| `data.contractVersion` | number | Drive agent contract version. Currently always `1` |
| `data.identity.scopeRef` | string | Opaque 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 |
| `data.identity.portalId` | string | Bitrix24 portal ID on the Vibecode platform |
| `data.identity.nativeUserId` | string | ID of the Bitrix24 user on whose behalf calls run. Employee list: [`GET /v1/users`](/docs/entities/users/list) |
| `data.identity.accountGeneration` | string | Binding generation. Grows when the binding credentials change. After it grows, previously issued search cursors and sync descriptors are not accepted |
| `data.search.available` | boolean | Whether [Drive search](/docs/disk/search) is available on the Bitrix24 account |
| `data.search.filters` | string[] | Search filter fields: `storageId`, `folderId`, `fileType` |
| `data.search.types` | string[] | Values of the search `type` field: `file`, `folder`, `all` |
| `data.search.queryMin` | number | Minimum search string length, `3` |
| `data.search.queryMax` | number | Maximum search string length, `255` |
| `data.sync.available` | boolean | Whether sync is available. With `false`, the `sync` object contains only three fields: `available`, `statusAvailable`, `retryAvailable` |
| `data.sync.statusAvailable` | boolean | Whether sync status is available. Equals `data.sync.available` |
| `data.sync.retryAvailable` | boolean | Whether a sync retry is available. Equals `data.sync.available` |
| `data.sync.schemaVersion` | number | Only with `available: true`. Sync schema version of the Bitrix24 account: `1` or `2` |
| `data.sync.cardSections` | object | Only with `available: true`. Which object card sections the Bitrix24 account returns: `metadata`, `location`, `access`, `relations`, each flagged `true` or `false` |
| `data.sync.changeTypes` | string[] | Only with `available: true`. Change types in the journal: `update`, `tombstone`, `accessChanged`, `indexUpdated` |
| `data.sync.limits.pageSizeMax` | number | Only with `available: true`. Maximum objects per sync page |
| `data.sync.limits.pageSizeMaxHeavy` | number | Only with `available: true`. Maximum objects per page when the `location`, `access`, or `relations` sections are requested |
| `data.sync.limits.checkBatchMax` | number | Only 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](/docs/disk/sync-check) by an `objectIds` list outside sync accepts 1 to 50 IDs whatever this field reports. May be absent |
| `data.sync.retention.journalRetentionDays` | number | Only with `available: true`. How many days the Bitrix24 account keeps the change journal |
| `data.sync.retention.interactionWindowDays` | number | Only with `available: true`. Depth of the user's file activity history, in days |
| `data.sync.retention.safeWindowSeconds` | number | Only with `available: true`. Change journal consistency window in seconds, as reported by the Bitrix24 account |
| `data.sync.pollBounds.minSeconds` | number | Only with `available: true`. Minimum change polling interval in seconds |
| `data.sync.pollBounds.recommendedSeconds` | number | Only with `available: true`. Recommended polling interval in seconds |
| `data.sync.pollBounds.maxSeconds` | number | Only with `available: true`. Maximum polling interval in seconds |
| `data.sync.executionBudgetMs` | number | Only with `available: true`. How many milliseconds one sync attempt is allotted. The platform sets the value; a request cannot change it |
| `data.save.create` | boolean | Whether a new file can be [uploaded](/docs/disk/uploads) |
| `data.save.version` | boolean | Whether a new version of an existing file can be uploaded |
| `data.save.reserveAvailable` | boolean | Whether an [upload can be reserved](/docs/disk/uploads-reserve). `true` if `create` or `version` is available |
| `data.save.maxBytes` | number | Maximum upload file size in bytes: `26214400`, 25 MiB |
| `data.save.atomicConcurrency` | boolean | Always `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 |
| `data.reason` | string | Why 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](/docs/disk#error-codes).

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `TOKEN_MISSING` | The key has no authorization configured on the Bitrix24 portal |
| 401 | `DISK_AUTH_UNAVAILABLE` | The 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 |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key is not recognized |
| 401 | `TOKEN_REFRESH_FAILED` | Failed to refresh the Bitrix24 portal authorization for the key. Retrying will not help until the key is authorized again |
| 403 | `SCOPE_DENIED` | The key does not have the `disk` scope |
| 403 | `DISK_ACCESS_DENIED` | Bitrix24 denied the user access while reading capabilities |
| 501 | `DISK_UNSUPPORTED` | The Bitrix24 portal did not return the list of available methods in the expected form |
| 502 | `DISK_READ_UNAVAILABLE` | The read failed for a reason not covered by the other codes. Retry the request later |
| 503 | `QUERY_LIMIT_EXCEEDED` | The Bitrix24 portal throttled the request rate |
| 503 | `BITRIX_TIMEOUT` | The Bitrix24 portal did not respond in time |
| 503 | `QUEUE_OVERFLOW`, `QUEUE_TIMEOUT` | The Bitrix24 portal call queue is full. The `Retry-After` header gives the delay before retrying |
| 503 | `user_self_deletion_pending` | The key owner requested deletion of their account, so Drive calls are stopped |
| 503 | `RATE_LIMITED` | The Bitrix24 portal responded with HTTP 429. The `Retry-After` header gives the delay before retrying |
| 503 | `ERROR_LOOP_DETECTED` | Repeated errors from this key on this method temporarily stopped calls. The `Retry-After` header gives the delay |

Full list of common API errors: [Errors](/docs/errors).

## Known specifics

**Unavailable sync does not affect the rest.** With `sync.available: false`, [search](/docs/disk/search), file upload, and [visibility checks](/docs/disk/sync-check) on an `objectIds` list still work.

**Read-only key.** For a key with the read-only [access mode](/docs/keys-auth/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

- [Drive search](/docs/disk/search)
- [Reserve a file upload to Drive](/docs/disk/uploads-reserve)
- [Upload file content to Drive](/docs/disk/uploads)
- [Check Drive object visibility](/docs/disk/sync-check)
- [Key access mode](/docs/keys-auth/access-mode)
- [Errors](/docs/errors)