## Drive agent

The Drive agent searches for files and folders on Bitrix24 Drive, writes files, and checks whether objects are visible to the user.

**Scope:** `disk` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key`, plus `Authorization: Bearer` for an OAuth application

All calls run on behalf of a single Bitrix24 user: the owner of the personal key or the user of the OAuth application session. The agent sees only what this user can access.

[`GET /v1/disk/capabilities`](/docs/disk/capabilities) reports what is available on the Bitrix24 account. Call it first: search, upload, and sync each have their own flag and do not depend on each other.

A file is written in two steps. The reservation records what to write and where, and returns an `operationId`. The upload sends the content under this `operationId` and writes to Bitrix24 exactly once. Repeating the same request does not create a second file; it returns the operation that was already written. So store the `operationId` before uploading, and after a failure read the operation instead of uploading again.

IDs and sizes in agent responses are strings. The search cursor and the operation list cursor are opaque: pass them back unchanged.

## Quick start

Check the capabilities and find files whose name contains `report`:

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

curl -X POST https://vibecode.bitrix24.com/v1/disk/search \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "report", "type": "file", "limit": 10 }'
```

## Full example

Write a text file to a folder and read the operation result. The script targets Node.js 18 or later, with the key in the `VIBE_API_KEY` environment variable. Take the folder ID from [`GET /v1/folders`](/docs/entities/folders/list) or from the storage `rootFolderId` field in [`GET /v1/storages/:id`](/docs/entities/storages/get).

```javascript
import { createHash, randomUUID } from 'node:crypto'

const API = 'https://vibecode.bitrix24.com/v1'
const headers = { 'X-Api-Key': process.env.VIBE_API_KEY, 'Content-Type': 'application/json' }

async function call(method, path, body) {
  const res = await fetch(API + path, { method, headers, body: body && JSON.stringify(body) })
  const json = await res.json()
  if (!json.success) throw new Error(`${path}: ${res.status} ${json.error.code}`)
  return json.data
}

// 1. Check that upload is available
const caps = await call('GET', '/disk/capabilities')
if (!caps.save.create) throw new Error('Uploading new files is not available to this key')

// 2. Reserve an upload to the folder
const folderId = '1'
const name = `report-${Date.now()}.txt`
const bytes = Buffer.from('Weekly report\n')
const contentHash = createHash('sha256').update(bytes).digest('hex')
const intent = [1, 'create', folderId, contentHash, String(bytes.length), null, name, 'createFail']
const reserve = await call('POST', '/disk/uploads/reserve', {
  reserveRequestId: randomUUID(),
  intent,
  lineage: { kind: 'initial' },
})

// 3. Send the content
const upload = await call('POST', '/disk/uploads', {
  operationId: reserve.operationId,
  intentHash: reserve.intentHash,
  effectiveFilename: name,
  content: bytes.toString('base64'),
  contentHash,
})
console.log('Write:', upload.application, 'file', upload.fileId)

// 4. Read the operation later, for example after the application restarts
const op = await call('GET', `/disk/uploads/${reserve.operationId}`)
console.log('Verification:', op.verification)
```

Run output:

```text
Write: applied file 10903
Verification: matched
```

In a production application, save `reserveRequestId`, `intent`, and `operationId` to your own storage before each subsequent step. Then, after a failure, repeating the same request returns the operation that was already created.

## Endpoint reference

| Method | Path | Description |
|-------|------|----------|
| GET | [`/v1/disk/capabilities`](/docs/disk/capabilities) | Drive agent capabilities on the Bitrix24 account |
| POST | [`/v1/disk/search`](/docs/disk/search) | Search files and folders |
| POST | [`/v1/disk/uploads/reserve`](/docs/disk/uploads-reserve) | Reserve an upload |
| POST | [`/v1/disk/uploads`](/docs/disk/uploads) | Upload content under a reservation |
| GET | [`/v1/disk/uploads`](/docs/disk/uploads-list) | List upload operations |
| GET | [`/v1/disk/uploads/:operationId`](/docs/disk/uploads-get) | Upload operation |
| POST | [`/v1/disk/sync/check`](/docs/disk/sync-check) | Check object visibility |

## Error codes

Drive agent errors arrive in the envelope `{ "success": false, "error": { "code", "message", "retrySafe" } }`. Their `message` field is always `Disk request unavailable`, so base decisions on `code`.

### Drive agent errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | The request body or parameters failed validation |
| 401 | `DISK_AUTH_UNAVAILABLE` | The Bitrix24 user could not be confirmed |
| 403 | `DISK_ACCESS_DENIED` | Bitrix24 denied the user access |
| 403, 409 | `DISK_GENERATION_STALE` | The search cursor is stale (403), or the key connection changed during a write (409) |
| 409 | `DISK_OPERATION_CONFLICT` | The request was repeated with a different body, or the content does not match the reservation |
| 409 | `DISK_OPERATION_EXPIRED` | The operation was not found, or the reservation has expired |
| 409 | `DISK_PRIOR_REQUIRED` | The prior operation to continue or retry was not found, is not finished, or does not match `lineage.kind` |
| 409 | `DISK_OUTCOME_UNKNOWN` | The outcome of the prior operation is unknown, so continuing from it is not accepted |
| 409 | `DISK_VERSION_CONFLICT` | The file changed after its state was read |
| 413 | `DISK_UPLOAD_TOO_LARGE` | The file is larger than 25 MiB |
| 501 | `DISK_UNSUPPORTED` | The portal does not support the capability |
| 502 | `DISK_READ_UNAVAILABLE` | Reading from the portal failed |

### System errors

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `TOKEN_MISSING` | The key has no Bitrix24 connection |
| 403 | `SCOPE_DENIED` | The key does not have the `disk` scope |
| 403 | `WRITE_BLOCKED_READONLY` | A read-only key cannot upload files |
| 503 | `QUERY_LIMIT_EXCEEDED` | Bitrix24 throttled the request rate |

The conditions for each code are on the endpoint pages. Full list of common errors: [Errors](/docs/errors).

## See also

- [Files](/docs/entities/files)
- [Folders](/docs/entities/folders)
- [Storages](/docs/entities/storages)
- [Key access mode](/docs/keys-auth/access-mode)
- [Errors](/docs/errors)