Para agentes de IA: markdown de esta página — /docs-content-en/disk/uploads.md índice de la documentación — /llms.txt

Los artículos de la documentación están disponibles actualmente en inglés.

Upload file content to Drive

POST /v1/disk/uploads

To read the outcome of the whole upload chain, send X-Disk-Upload-Response-Version: 2 on every upload request: reserve, apply, status, and list. Without the header, the strict v1 response describes the individual attempt. Other header values return 400 INVALID_PARAMS.

Writes a file to Bitrix24 Drive under a previously reserved operation — creates a new file or a new version of an existing one, as set at reserve time.

The body is flat, with no fields wrapper.

Request fields (body)

Field Type Required Description
FieldoperationId Typestring Requiredyes DescriptionOperation ID from the POST /v1/disk/uploads/reserve response. A lost ID can be found in GET /v1/disk/uploads
FieldintentHash Typestring Requiredyes DescriptionThe intentHash field from the reserve response — 64 lowercase characters
FieldeffectiveFilename Typestring Requiredyes DescriptionFile name matching the reserve's intent[6] character for character
Fieldcontent Typestring Requiredyes DescriptionFile bytes in base64 per RFC 4648: alphabet A-Z, a-z, 0-9, +, /, padding =, with no line breaks and no data: prefix. At most 26214400 bytes after decoding (25 MiB)
FieldcontentHash Typestring Requiredyes DescriptionSHA-256 of the file bytes before base64 encoding — 64 lowercase characters. Matches the reserve's intent[3]

The body accepts no other fields: an unknown field returns 400 INVALID_PARAMS. The total request body size is at most 35 MiB.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/disk/uploads \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Disk-Upload-Response-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU",
    "intentHash": "3e10ae1152a0e4b4e89d3b312bfacafc1f3e0cf22d8a5eae3e231fa8bc274498",
    "effectiveFilename": "vibe-disk-docs-check-2.txt",
    "content": "VmliZSBEaXNrIGFnZW50IGRvY3MgY2hlY2sgMgo=",
    "contentHash": "6be5cdb4cdbf136301c74adf2fd5a380fe5ceda1e998ce4b62f01cf7d20589a5"
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/disk/uploads \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "X-Disk-Upload-Response-Version: 2" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU",
    "intentHash": "3e10ae1152a0e4b4e89d3b312bfacafc1f3e0cf22d8a5eae3e231fa8bc274498",
    "effectiveFilename": "vibe-disk-docs-check-2.txt",
    "content": "VmliZSBEaXNrIGFnZW50IGRvY3MgY2hlY2sgMgo=",
    "contentHash": "6be5cdb4cdbf136301c74adf2fd5a380fe5ceda1e998ce4b62f01cf7d20589a5"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/disk/uploads', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Disk-Upload-Response-Version': '2',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    operationId: 'xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU',
    intentHash: '3e10ae1152a0e4b4e89d3b312bfacafc1f3e0cf22d8a5eae3e231fa8bc274498',
    effectiveFilename: 'vibe-disk-docs-check-2.txt',
    content: 'VmliZSBEaXNrIGFnZW50IGRvY3MgY2hlY2sgMgo=',
    contentHash: '6be5cdb4cdbf136301c74adf2fd5a380fe5ceda1e998ce4b62f01cf7d20589a5',
  }),
})

const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
if (data.application === 'unknown') {
  console.warn('Write result unknown:', data.operationId)
} else if (data.application === 'applied') {
  console.log('Content confirmed:', data.operationId)
  if (data.fileId) console.log('File for this attempt:', data.fileId, data.safeLink)
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/disk/uploads', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'X-Disk-Upload-Response-Version': '2',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    operationId: 'xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU',
    intentHash: '3e10ae1152a0e4b4e89d3b312bfacafc1f3e0cf22d8a5eae3e231fa8bc274498',
    effectiveFilename: 'vibe-disk-docs-check-2.txt',
    content: 'VmliZSBEaXNrIGFnZW50IGRvY3MgY2hlY2sgMgo=',
    contentHash: '6be5cdb4cdbf136301c74adf2fd5a380fe5ceda1e998ce4b62f01cf7d20589a5',
  }),
})

const { success, data, error } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue if the request was processed. Whether the file was written is shown by data.application
Fielddata.operationId Typestring DescriptionOperation ID
Fielddata.phase Typestring DescriptionOperation stage: prepared — reserved, submitting — the write has been sent to Bitrix24, settled — finished
Fielddata.application Typestring DescriptionContent result for the whole attempt chain: applied — requested bytes were observed, not_applied — proven no dispatch, unknown — effect remains unproven
Fielddata.attemptApplication Typestring DescriptionThis attempt’s result: not_applied, unknown or applied
Fielddata.proofSource Typestring | null DescriptionChain proof source: native_ack, current_content, version_content or null
Fielddata.proofOperationId Typestring | null DescriptionID of the attempt providing chain proof, or null
Fielddata.verification Typestring DescriptionCheck against the current state of the file: matched — the file matches what was written, superseded — the file has changed since, unavailable — the check was not performed
Fielddata.fileId Typestring DescriptionFile ID from this attempt's receipt, when applied. Another attempt may have proved the chain result. Used as intent[2] in version mode
Fielddata.contentFileId Typestring DescriptionContent ID from this attempt's receipt, when available; it need not be the file's current version
Fielddata.contentGeneration Typestring DescriptionGeneration from this attempt's applied receipt, when available; it may differ from the current file generation
Fielddata.safeLink Typestring DescriptionHTTPS address of the file in Bitrix24. Returned when Bitrix24 provided it. Access is limited by the employee's permissions in Bitrix24
Fielddata.atomicConcurrency Typeboolean DescriptionAlways false: the write is not protected against another user changing the file at the same time
Fielddata.conflictDetected Typeboolean Descriptiontrue if, in version mode, the current state of the file did not match intent[5] and no write was performed
Fielddata.outcomeUnknown Typeboolean Descriptiontrue if this attempt remains unknown, even if the chain later becomes applied
Fielddata.uncertainAncestorOperationId Typestring DescriptionUnresolved ancestor ID; a different-content successor requires positive content proof

Response example

File written:

JSON 
{
  "success": true,
  "data": {
    "operationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU",
    "phase": "settled",
    "application": "applied",
    "attemptApplication": "applied",
    "proofSource": "native_ack",
    "proofOperationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU",
    "verification": "matched",
    "fileId": "10901",
    "contentFileId": "39571",
    "contentGeneration": "1",
    "safeLink": "https://example.bitrix24.com/company/personal/user/1/disk/file/vibe-disk-docs-check-2.txt",
    "atomicConcurrency": false,
    "conflictDetected": false,
    "outcomeUnknown": false
  }
}

The write was sent but not confirmed — the folder already had a file with that name:

JSON 
{
  "success": true,
  "data": {
    "operationId": "zQl-VU0ZeSeCYnH14kibBVeiYRM7iihEu6-QDSTPJFQ",
    "phase": "settled",
    "application": "unknown",
    "attemptApplication": "unknown",
    "proofSource": null,
    "proofOperationId": null,
    "verification": "unavailable",
    "atomicConcurrency": false,
    "conflictDetected": false,
    "outcomeUnknown": true
  }
}

Error response example

409 — contentHash does not match the SHA-256 of the bytes sent:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe body failed validation: a required field is missing, intentHash or contentHash is not 64 hexadecimal characters, the file name is invalid, or the body has an unknown field
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no connection to Bitrix24
HTTP401 CodeDISK_AUTH_UNAVAILABLE DescriptionThe Bitrix24 user could not be confirmed: an application key was sent without Authorization: Bearer, the session does not belong to the key's application, or the key is not supported by the Drive agent
HTTP401 CodeDISK_AUTH_UNAVAILABLE Descriptionversion mode: the current state of the file could not be read. No write was performed; the operation finished with application: "not_applied"
HTTP401 CodeTOKEN_REFRESH_FAILED DescriptionThe portal authorization for the key could not be refreshed. A retry does not help until the key is authorized again
HTTP403 CodeSCOPE_DENIED DescriptionThe key has no disk scope
HTTP403 CodeWRITE_BLOCKED_READONLY DescriptionThe key is in read-only mode
HTTP403 CodeDISK_ACCESS_DENIED DescriptionBitrix24 denied access while checking the user
HTTP409 CodeDISK_OPERATION_CONFLICT Descriptioncontent is not base64 per RFC 4648, contentHash does not match the SHA-256 of the bytes, or intentHash, effectiveFilename, the hash or the byte size does not match the reserve
HTTP409 CodeDISK_OPERATION_EXPIRED DescriptionThe operationId operation was not found in the key's context or its reservationExpiresAt deadline has passed. Create a new reserve
HTTP409 CodeDISK_VERSION_CONFLICT Descriptionversion mode: the current state of the file did not match intent[5]. No write was performed; the operation finished with application: "not_applied" and conflictDetected: true
HTTP409 CodeDISK_OUTCOME_UNKNOWN DescriptionA same-content retry could not verify the current file before dispatch. No new write was sent; the earlier attempt remains uncertain. Check the operation before retrying.
HTTP413 CodeDISK_UPLOAD_TOO_LARGE DescriptionThe content exceeds 26214400 bytes after decoding
HTTP413 CodePAYLOAD_TOO_LARGE DescriptionThe request body exceeds 35 MiB
HTTP429 CodeLARGE_BODY_BACKEND_BUSY DescriptionThe server is processing many large requests at once. The response carries a Retry-After header with the pause in seconds
HTTP502 CodeDISK_READ_UNAVAILABLE DescriptionBitrix24 returned an error that Vibecode did not recognize
HTTP503 CodeQUERY_LIMIT_EXCEEDED DescriptionBitrix24 limited the request rate. Retry later
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time
HTTP503 CodeQUEUE_OVERFLOW, QUEUE_TIMEOUT DescriptionThe portal call queue is full. The Retry-After header gives the pause before a retry
HTTP503 CodeRATE_LIMITED DescriptionThe portal responded with HTTP 429. The Retry-After header gives the pause before a retry
HTTP503 CodeERROR_LOOP_DETECTED DescriptionRepeated errors of this key on this method have temporarily stopped calls. The Retry-After header gives the pause
HTTP503 Codeuser_self_deletion_pending DescriptionThe key owner requested deletion of their account — Drive calls are stopped

Full list of common API errors — Errors.

Known specifics

  • The write is sent to Bitrix24 once. Vibecode does not retry it on its own, either on a timeout or on a connection failure. If Bitrix24 did not confirm a sent write — refused, did not respond or responded incompletely — the operation finishes with application: "unknown", and a repeat call with the same operationId returns that state without a new write.
  • After an unknown cloud version upload, the agent may explicitly retry the same bytes. Wait at least five minutes after the uncertain attempt settles, reserve lineage.kind: "retry" from the latest attempt with the exact same intent, and submit the original bytes again. Before another dispatch, Vibecode reads the current file and checks SHA-256: matching content proves applied without another write; an unchanged original file permits one dispatch; a detected foreign edit returns DISK_VERSION_CONFLICT without dispatch; a read failure leaves the outcome unknown. The original call may complete later. The file can also change between the check and the write.
  • create mode does not overwrite a file. If the folder already has a file with the same name, the existing file stays unchanged and the operation finishes with application: "unknown". To replace content, use version mode.
  • Repeating a finished operation recalculates verification. For application: "applied", the field is checked against the current file again.
  • The intent[5] check in version mode runs before the write and does not lock the file. A change to the file between the check and the write is not detected. After 409 DISK_VERSION_CONFLICT, take the current contentFileId, contentGeneration and size and reserve a new operation.

See also