## 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 |
|----------|-----|:-----:|----------|
| `operationId` (path) | string | yes | Operation ID, from 1 to 512 characters. Source: the [`POST /v1/disk/uploads/reserve`](/docs/disk/uploads-reserve) response or the [`GET /v1/disk/uploads`](/docs/disk/uploads-list) list |

## Examples

### curl — personal key

```bash
curl https://vibecode.bitrix24.com/v1/disk/uploads/xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
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 |
|------|-----|----------|
| `success` | boolean | `true` on a successful read |
| `data.operationId` | string | Operation ID |
| `data.phase` | string | Operation phase: `prepared` — reserved, `submitting` — the write has been sent to Bitrix24, `settled` — finished |
| `data.application` | string | Write outcome: `applied` — Bitrix24 confirmed the write, `not_applied` — the write was not sent to Bitrix24, `unknown` — the write was sent but not confirmed |
| `data.verification` | string | Check 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 |
| `data.fileId` | string | File ID on Drive. Returned when `application: "applied"` |
| `data.contentFileId` | string | ID of the content written by this operation. Returned when `application: "applied"` |
| `data.contentGeneration` | string | Version number of the content written by this operation. Returned when `application: "applied"` |
| `data.safeLink` | string | HTTPS address of the file in Bitrix24. Returned when Bitrix24 provides it. Access is limited by the employee's permissions in Bitrix24 |
| `data.atomicConcurrency` | boolean | Always `false`: the write is not protected against another user changing the file at the same time |
| `data.conflictDetected` | boolean | `true` if, in `version` mode, the file state did not match the expected one and the write was not performed |
| `data.outcomeUnknown` | boolean | `true` 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 |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `operationId` is longer than 512 characters |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key is not recognized |
| 401 | `TOKEN_MISSING` | The key has no connection to Bitrix24 |
| 401 | `DISK_AUTH_UNAVAILABLE` | The 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 |
| 401 | `TOKEN_REFRESH_FAILED` | The portal authorization for the key could not be refreshed. A retry does not help until the key is authorized again |
| 403 | `SCOPE_DENIED` | The key lacks the `disk` scope |
| 403 | `DISK_ACCESS_DENIED` | Bitrix24 denied access while checking the user |
| 409 | `DISK_OPERATION_EXPIRED` | There 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 |
| 502 | `DISK_READ_UNAVAILABLE` | Bitrix24 returned an error that Vibecode did not recognize |
| 503 | `QUERY_LIMIT_EXCEEDED` | Bitrix24 throttled the request rate. Retry later |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |
| 503 | `QUEUE_OVERFLOW`, `QUEUE_TIMEOUT` | The portal call queue is full. The `Retry-After` header gives the pause before a retry |
| 503 | `RATE_LIMITED` | The portal responded with HTTP 429. The `Retry-After` header gives the pause before a retry |
| 503 | `ERROR_LOOP_DETECTED` | Repeated errors from this key on this method have temporarily paused calls. The `Retry-After` header gives the pause |
| 503 | `user_self_deletion_pending` | The key owner requested deletion of their account — Drive calls are stopped |

Full list of common API errors — [Errors](/docs/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`](/docs/disk/search) or [`POST /v1/disk/sync/check`](/docs/disk/sync-check).

## See also

- [List upload operations](/docs/disk/uploads-list)
- [Reserve a file upload to Drive](/docs/disk/uploads-reserve)
- [Upload file content to Drive](/docs/disk/uploads)
- [Search Drive](/docs/disk/search)
- [Errors](/docs/errors)