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 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 dispatches one Bitrix24 call. Reusing that operationId never dispatches another write. After a timeout, read the operation; if the outcome stays unknown, a file version can be explicitly reserved again with the same content after checking the current file.

Send X-Disk-Upload-Response-Version: 2 on reserve, upload, operation status, and list requests to read the outcome of the whole chain. Without it, the strict v1 response describes the individual attempt.

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:

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 or from the storage rootFolderId field in GET /v1/storages/:id.

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 requestHeaders = path.startsWith('/disk/uploads')
    ? { ...headers, 'X-Disk-Upload-Response-Version': '2' } : headers
  const res = await fetch(API + path, { method, headers: requestHeaders, 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:

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

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

System errors

The conditions for each code are on the endpoint pages. Full list of common errors: Errors.

See also

• Files
• Folders
• Storages
• Key access mode
• Errors