## Download a file version

`GET /v1/files/:id/versions/:versionId/download`

Downloads the content of the selected file version through the Vibecode API. The platform adds the Bitrix24 authorization itself, so you do not need to pass a Bitrix24 account token.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `id` (path) | number | yes | File ID. Get it: `GET /v1/files?folderId=X` |
| `versionId` (path) | number | yes | ID of a version of this file. List: [`GET /v1/files/:id/versions`](./versions.md) |

The request has no body.

## Examples

### curl — personal key

```bash
# Save under the name from the Content-Disposition header
curl -OJ -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/files/205/versions/410/download

# Set the file name explicitly
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/files/205/versions/410/download \
  -o report-v3.txt
```

### curl — OAuth application

```bash
curl -OJ \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.com/v1/files/205/versions/410/download
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/files/205/versions/410/download', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

if (!res.ok) {
  const body = await res.json()
  throw new Error(body.error?.code ?? String(res.status))
}

const fileName = decodeURIComponent(
  res.headers.get('Content-Disposition')?.match(/filename="(.+?)"/)?.[1] ?? 'file'
)
const bytes = new Uint8Array(await res.arrayBuffer())
console.log(fileName, bytes.length, 'bytes')
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/files/205/versions/410/download', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

if (!res.ok) {
  const body = await res.json()
  throw new Error(body.error?.code ?? String(res.status))
}

const bytes = new Uint8Array(await res.arrayBuffer())
```

## Response fields

On success, the HTTP status is `200 OK` and the response body is the bytes of the version content. File details come in the headers.

| Header | Example value | Description |
|-----------|-----------------|----------|
| `Content-Type` | `text/plain; charset=UTF-8` | Content type that Bitrix24 returned for the file |
| `Content-Disposition` | `attachment; filename="report.txt"` | File name in this version. Non-Latin characters and spaces in the name arrive percent-encoded — decode the name with the `decodeURIComponent` function |
| `Content-Length` | `10` | Size of the version content in bytes |

## Response example

```http
HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Content-Disposition: attachment; filename="report.txt"
Content-Length: 10

<version content, 10 bytes>
```

## Error response example

404 — this file has no such version:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "File version not found."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 404 | `ENTITY_NOT_FOUND` | The version with this `versionId` does not exist, was removed from the history, or belongs to a different file |
| 404 | `DOWNLOAD_URL_NOT_FOUND` | The version has no download address |
| 400 | `INVALID_ID` | `id` or `versionId` is not a positive integer |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `TOKEN_MISSING` | Bitrix24 access tokens are unavailable |
| 403 | `SCOPE_DENIED` | The key lacks the `disk` scope |
| 502 | `DOWNLOAD_FAILED` | Bitrix24 returned an error during the download |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **The `disk` scope is required.** Unlike [`GET /v1/files/:id/download`](./download.md), downloading a version does not accept a key that holds only the `crm` scope.
- **A version's `downloadUrl` is a path without the domain.** In the responses of [`GET /v1/files/:id/versions`](./versions.md) and [`GET /v1/files/:id/versions/:versionId`](./version.md) it looks like `/v1/files/205/versions/410/download`: prepend `https://vibecode.bitrix24.com` to it before sending the request. The address is permanent and contains no authorization token.

## See also

- [File version history](/docs/entities/files/versions)
- [Read a file version](/docs/entities/files/version)
- [Download file](/docs/entities/files/download)
- [Files](/docs/entities/files)