For AI agents: markdown of this page — /docs-content-en/disk/uploads-get.md documentation index — /llms.txt

Get an upload operation

GET /v1/disk/uploads/:operationId

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"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/disk/uploads/xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -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' },
})

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',
    '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 DescriptionWrite outcome: applied — Bitrix24 confirmed the write, not_applied — the write was not sent to Bitrix24, unknown — the write was sent but not confirmed
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. Returned when application: "applied"
Fielddata.contentFileId Typestring DescriptionID of the content written by this operation. Returned when application: "applied"
Fielddata.contentGeneration Typestring DescriptionVersion number of the content written by this operation. Returned when application: "applied"
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 when application: "unknown"

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",
    "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.
  • The unknown state does not change on its own. Reading does not check whether the file appeared after an unconfirmed write. Find the file with POST /v1/disk/search or POST /v1/disk/sync/check.

See also