## Download file

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

Downloads file contents through the Vibecode proxy with automatic authorization. Unlike the `downloadUrl` field in the `GET /v1/files/:id` response, this endpoint adds authorization on every call — you do not need to extract and insert the token manually. The response is a binary stream with a `Content-Disposition` header; browsers offer to save the file automatically.

## Parameters

| Parameter | In | Type | Required | Description |
|----------|---|-----|:-----:|----------|
| `id` | path | number | yes | File ID. Get it: `GET /v1/files` or `GET /v1/files/:id` |

The request body is empty.

## Examples

### curl — personal key

```bash
# Save to a file using the original name from the Content-Disposition header
curl -OJ -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/files/205/download

# Specify the file name explicitly
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/files/205/download \
  -o myfile.pdf
```

### curl — OAuth app

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

### JavaScript — personal key

```javascript
const fileId = 205

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/files/${fileId}/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))
}

// Save the blob in the browser
const blob = await res.blob()
const url = URL.createObjectURL(blob)
const a = document.createElement('a')
a.href = url
a.download = res.headers.get('Content-Disposition')?.match(/filename="(.+?)"/)?.[1] ?? 'file'
a.click()
URL.revokeObjectURL(url)
```

### JavaScript — OAuth app

```javascript
const fileId = 205

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/files/${fileId}/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 blob = await res.blob()
```

## Response headers

On success the binary file contents are returned (HTTP 200). There is no `## Response fields` section — the response body is not JSON.

| Header | Example value | Description |
|-----------|-----------------|----------|
| `Content-Type` | `application/pdf` | Content type. Depends on the file type: `text/plain`, `image/png`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, etc. |
| `Content-Disposition` | `attachment; filename="report.pdf"` | File name for saving. Browsers use it automatically when downloading |
| `Content-Length` | `31232` | File size in bytes. Sent if known from metadata |

## Error response example

404 — file not found:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Could not find entity with id '99999999'."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not provided |
| 401 | `INVALID_API_KEY` | Invalid or expired key |
| 403 | `SCOPE_DENIED` | The key lacks the `disk` scope |
| 404 | `ENTITY_NOT_FOUND` | A file with this `id` does not exist or is not accessible to the key |
| 404 | `DOWNLOAD_URL_NOT_FOUND` | The file has no download address |
| 502 | `DOWNLOAD_FAILED` | Bitrix24 returned an error during proxying (for example, `403`) |

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

## Known specifics

- **Authorization is added automatically.** For OAuth app keys, Vibecode adds the authorization token to the request on every call. For webhook keys the token is already embedded in the address — Vibecode uses the address as is.
- **The `downloadUrl` field from `GET /v1/files/:id` is temporary.** This endpoint (`/download`) is the stable way to download: each time it fetches the current address and adds authorization. Accessing a saved `downloadUrl` directly may fail once the token expires.

## See also

- [Get file](/docs/entities/files/get) — `GET /v1/files/:id`
- [List files](/docs/entities/files/list) — `GET /v1/files`
- [Files](/docs/entities/files)