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

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 — личный ключ

Terminal 
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-приложение

Terminal 
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)

Полный список общих ошибок — Ошибки.

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