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

List upload operations

GET /v1/disk/uploads

Returns Bitrix24 Drive file upload operations created in the key context: unfinished or recently finished. Helps recover a lost operation ID and find records with an unknown outcome.

Parameters

Parameter Type Required Default Description
Parameterfilter (query) Typestring Requiredyes Default— Descriptionpending — operations in progress: phase is prepared or submitting, or application is unknown. recent — finished operations with application equal to applied or not_applied, created within the last 90 days
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionRecords per page, an integer from 1 to 100
Parametercursor (query) Typestring Requiredno Default— DescriptionThe nextCursor value from the previous response. Omit it in the first request

The request accepts no other parameters: an unknown parameter returns 400 INVALID_PARAMS.

Records are sorted from oldest to newest. While the response has hasMore: true, request the next page with cursor set to nextCursor and the same filter.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/disk/uploads?filter=recent&limit=2" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/disk/uploads?filter=recent&limit=2" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const items = []
let cursor
do {
  const params = new URLSearchParams({ filter: 'recent', limit: '2' })
  if (cursor) params.set('cursor', cursor)
  const res = await fetch(`https://vibecode.bitrix24.com/v1/disk/uploads?${params}`, {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  })
  const { success, data, error } = await res.json()
  if (!success) throw new Error(error.code)
  items.push(...data.items)
  cursor = data.hasMore ? data.nextCursor : undefined
} while (cursor)

console.log(items.map(item => `${item.intentSummary.effectiveFilename}: ${item.application}`))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/disk/uploads?filter=recent&limit=2', {
  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.items Typearray DescriptionOperations on the page. An empty array if nothing matches filter
Fielddata.items[].operationId Typestring DescriptionOperation ID. Details: GET /v1/disk/uploads/:operationId
Fielddata.items[].phase Typestring DescriptionOperation phase: prepared, submitting or settled
Fielddata.items[].application Typestring DescriptionWrite outcome: applied, not_applied or unknown
Fielddata.items[].verification Typestring DescriptionResult of the last check against the current file: matched, superseded or unavailable
Fielddata.items[].intentSummary.mode Typestring DescriptionMode from the reservation: create or version
Fielddata.items[].intentSummary.targetId Typestring DescriptionFolder ID for create or file ID for version
Fielddata.items[].intentSummary.effectiveFilename Typestring DescriptionFile name from the reservation
Fielddata.items[].intentSummary.contentSize Typestring DescriptionFile size in bytes
Fielddata.items[].intentSummary.intentHash Typestring DescriptionThe operation's intentHash — required by POST /v1/disk/uploads
Fielddata.items[].priorOperationId Typestring DescriptionThe previous operation this one was reserved from. Returned for operations with lineage.kind equal to successor or retry
Fielddata.hasMore Typeboolean Descriptiontrue if there is a next page
Fielddata.nextCursor Typestring DescriptionCursor of the next page. Returned when hasMore: true

Response example

First page of filter=recent&limit=2:

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "operationId": "zSTFAm53NusAWc94THbRTOfbe-OIoHwlDIJTQ6E2Z7o",
        "phase": "settled",
        "application": "applied",
        "verification": "matched",
        "intentSummary": {
          "mode": "create",
          "targetId": "1",
          "effectiveFilename": "vibe-disk-docs-check.txt",
          "contentSize": "27",
          "intentHash": "3e55280c097b92721a6c58da586363f1169e7dec15990fe3fa7f44f543b8331a"
        }
      },
      {
        "operationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU",
        "phase": "settled",
        "application": "applied",
        "verification": "superseded",
        "intentSummary": {
          "mode": "create",
          "targetId": "1",
          "effectiveFilename": "vibe-disk-docs-check-2.txt",
          "contentSize": "29",
          "intentHash": "3e10ae1152a0e4b4e89d3b312bfacafc1f3e0cf22d8a5eae3e231fa8bc274498"
        }
      }
    ],
    "hasMore": true,
    "nextCursor": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU"
  }
}

The next page with cursor — the operation for a new file version carries priorOperationId:

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "operationId": "dlbBsp01PqU2VBXjA8VigHPCXE_T01lBJgCp_gNfypY",
        "phase": "settled",
        "application": "applied",
        "verification": "matched",
        "intentSummary": {
          "mode": "version",
          "targetId": "10901",
          "effectiveFilename": "vibe-disk-docs-check-2.txt",
          "contentSize": "32",
          "intentHash": "07b6444b0eb202f1c7c11b50d5617a86790e80e6bb9d487c0e90776d1a0f0a75"
        },
        "priorOperationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU"
      },
      {
        "operationId": "QSCV6zB59O811A1pNO9HfekQdMvGifw4_E9-y1OZs48",
        "phase": "settled",
        "application": "not_applied",
        "verification": "unavailable",
        "intentSummary": {
          "mode": "version",
          "targetId": "10901",
          "effectiveFilename": "vibe-disk-docs-check-2.txt",
          "contentSize": "16",
          "intentHash": "76d560e3bf0b2bfabb85152474db537ebb08225558e37537f9ff86fbafebe0ad"
        }
      }
    ],
    "hasMore": false
  }
}

Error response example

400 — limit is greater than 100:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionfilter is missing or is neither pending nor recent, limit is not an integer from 1 to 100, cursor is longer than 512 characters, or an unknown parameter is passed
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_CONFLICT Descriptioncursor is not an operation ID in the key context
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 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

  • verification is not recomputed in the list. The field carries the result of the last check. To check an operation against the current file, request GET /v1/disk/uploads/:operationId.

See also