## Скачать объект

`GET /v1/storage/objects/:key`

Возвращает содержимое объекта или временную ссылку для скачивания. Поведение определяется параметрами запроса: по умолчанию — перенаправление, `?inline=true` — содержимое в теле ответа.

## Параметры

**Путь**

| Параметр | Тип | Описание |
|----------|-----|---------|
| `key` | string | Ключ объекта. Символы `/` в ключе необходимо кодировать: `users%2F42%2Favatar.png` |

**Запрос**

| Параметр | Тип | По умолч. | Описание |
|----------|-----|-----------|---------|
| `inline` | boolean | `false` | `true` или `1` — вернуть содержимое непосредственно в теле ответа (HTTP 200) вместо перенаправления |
| `inline_render` | boolean | `false` | Только совместно с `?inline=true`. `true` или `1` — убирает заголовок `Content-Disposition`, браузер отображает файл вместо скачивания |
| `download` | string | — | Имя файла. При переходе по ссылке браузер предложит сохранить файл с указанным именем |

## Примеры

### curl — личный ключ

```bash
curl -L "https://vibecode.bitrix24.tech/v1/storage/objects/reports%2F2024%2Fannual.pdf" \
  -H "X-Api-Key: YOUR_API_KEY" \
  --output annual.pdf
```

### curl — OAuth-приложение

```bash
curl -L "https://vibecode.bitrix24.tech/v1/storage/objects/reports%2F2024%2Fannual.pdf" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  --output annual.pdf
```

### JavaScript — личный ключ

```javascript
// Получить временную ссылку (без следования по перенаправлению)
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/storage/objects/reports%2F2024%2Fannual.pdf',
  {
    redirect: 'manual',
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const url = res.headers.get('location') // временная ссылка, действует 10 минут
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/storage/objects/reports%2F2024%2Fannual.pdf',
  {
    redirect: 'manual',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const url = res.headers.get('location')
```

## Ответ

Формат ответа зависит от параметров запроса.

**По умолчанию — перенаправление**

Возвращает `302 Found` с временной ссылкой в заголовке `Location`. Ссылка действует 10 минут. Браузеры следуют перенаправлению автоматически; в серверном коде используйте `redirect: 'manual'` и читайте `response.headers.get('location')`.

```
HTTP/1.1 302 Found
Location: <временная ссылка>
Cache-Control: no-store
```

**`?inline=true` — содержимое в теле ответа**

Возвращает `200 OK` с содержимым объекта непосредственно в теле ответа. По умолчанию браузер сохраняет файл (заголовок `Content-Disposition: attachment`). Чтобы браузер отобразил файл вместо скачивания, добавьте `&inline_render=true`.

```
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 204800
ETag: "e3b0c44298fc1c149afbf4c8996fb92"
X-Content-Type-Options: nosniff
Content-Disposition: attachment; filename="annual.pdf"

<содержимое объекта>
```

**`?download=<имя>` — скачивание с заданным именем**

Возвращает `302 Found`. При переходе по ссылке из заголовка `Location` хранилище отдаёт файл с заголовком `Content-Disposition: attachment; filename="<имя>"`, поэтому браузер предложит сохранить его с указанным именем.

```
HTTP/1.1 302 Found
Location: <временная ссылка с указанным именем файла>
Cache-Control: no-store
```

## Пример ответа при ошибке

404 — объект не найден:

```json
{
  "success": false,
  "error": {
    "code": "STORAGE_OBJECT_NOT_FOUND",
    "message": "Object reports/2024/annual.pdf not found"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 401 | `MISSING_API_KEY` | API-ключ не передан |
| 403 | `STORAGE_SCOPE_REQUIRED` | У API-ключа нет скоупа `vibe:storage` |
| 404 | `STORAGE_OBJECT_NOT_FOUND` | Объект с указанным ключом не найден |
| 410 | `STORAGE_OBJECT_DELETED` | Объект был удалён |
| 502 | `STORAGE_OBJECT_STREAM_FAILED` | Ошибка при передаче содержимого объекта (только для режима `?inline=true`) |

Полный список общих ошибок — [Ошибки](/docs/errors).

## Смотрите также

- [Объекты](/docs/storage/objects)
- [Список объектов](/docs/storage/objects/list)
- [Метаданные объекта](/docs/storage/objects/head)
- [Загрузка](/docs/storage/upload)