Para agentes de IA: markdown desta página — /docs-content-en/disk/uploads-get.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Get an upload operation

GET /v1/disk/uploads/:operationId

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.

Shows the state of an operation that uploads a file to Bitrix24 Drive and checks the written file against its current state. The request does not resend the write in any operation state.

Parameters

Parameter Type Required Description
ParameteroperationId (path) Typestring Requiredyes DescriptionOperation ID, from 1 to 512 characters. Source: the POST /v1/disk/uploads/reserve response or the GET /v1/disk/uploads list

Examples

curl — personal key

Terminal 
curl https://vibecode.bitrix24.com/v1/disk/uploads/xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Disk-Upload-Response-Version: 2"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/disk/uploads/xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "X-Disk-Upload-Response-Version: 2" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const operationId = 'xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU'
const res = await fetch(`https://vibecode.bitrix24.com/v1/disk/uploads/${operationId}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'X-Disk-Upload-Response-Version': '2' },
})

const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
console.log(data.application, data.verification)

JavaScript — OAuth application

javascript 
const operationId = 'xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU'
const res = await fetch(`https://vibecode.bitrix24.com/v1/disk/uploads/${operationId}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'X-Disk-Upload-Response-Version': '2',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful read
Fielddata.operationId Typestring DescriptionOperation ID
Fielddata.phase Typestring DescriptionOperation phase: prepared — reserved, submitting — the write has been sent to Bitrix24, settled — finished
Fielddata.application Typestring DescriptionContent result for the chain: applied — current file content, a historical version SHA-256, or a native acknowledgement proves the requested bytes existed; not_applied — proven no dispatch; unknown — effect 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 file state at request time: matched — the file matches what was written, superseded — the file has changed since, unavailable — the check was not performed
Fielddata.fileId Typestring DescriptionFile ID on Drive when this attempt has its own applied receipt; the chain may be applied by another attempt
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 generation
Fielddata.safeLink Typestring DescriptionHTTPS address of the file in Bitrix24. Returned when Bitrix24 provides 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 file state did not match the expected one and the write was not performed
Fielddata.outcomeUnknown Typeboolean Descriptiontrue if this attempt remains unknown, even when the chain result is applied
Fielddata.uncertainAncestorOperationId Typestring DescriptionUnresolved ancestor ID; a different-content successor waits for positive content proof

Response example

The file was written by this operation but later received a new version:

JSON 
{
  "success": true,
  "data": {
    "operationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU",
    "phase": "settled",
    "application": "applied",
    "attemptApplication": "applied",
    "proofSource": "native_ack",
    "proofOperationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU",
    "verification": "superseded",
    "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
  }
}

Error response example

409 — there is no operation with this operationId in the key's context:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionoperationId is longer than 512 characters
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 passed without Authorization: Bearer, the session does not belong to the key's application, or the key is not supported by the Drive agent
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 lacks the disk scope
HTTP403 CodeDISK_ACCESS_DENIED DescriptionBitrix24 denied access while checking the user
HTTP409 CodeDISK_OPERATION_EXPIRED DescriptionThere is no operation with this operationId in the key's context: the ID is unknown, or the operation was created by another user, another key or another application
HTTP502 CodeDISK_READ_UNAVAILABLE DescriptionBitrix24 returned an error that Vibecode did not recognize
HTTP503 CodeQUERY_LIMIT_EXCEEDED DescriptionBitrix24 throttled 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 from this key on this method have temporarily paused 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

  • verification is recomputed on every request. For application: "applied", Vibecode reads the current file in Bitrix24 and compares it with the written content. superseded means the file has changed since, not that the write failed: application stays applied. If the file could not be read, unavailable is returned.
  • A read-only key can read operations. The request does not change data and is available to a read-only key, unlike reservation and upload.
  • unknown may later become applied. GET reports stored state and schedules neither reconciliation nor a write. Matching SHA-256 of the current file or any eligible historical version proves the requested bytes existed; among multiple matches the highest generation is selected. Unchanged history after a timeout does not prove absence. For a cloud version upload only, retry the same bytes with lineage.kind: "retry" after the wait; current-file preflight is mandatory. Create uploads cannot use this retry.

See also