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

GET /v1/storage/objects/:key

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

Параметры

Путь

Запрос

Примеры

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

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

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

// Получить временную ссылку (без следования по перенаправлению)
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-приложение

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 — объект не найден:

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

Ошибки

Метод ограничен 600 запросами в минуту на портал. Все API-ключи портала делят этот бюджет, а лимит делится между активными репликами платформы. Действующее значение приходит в x-ratelimit-limit; после 429 повторите запрос через время из Retry-After.

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

• Ключ приложения без сессии сотрудника видит только общий файл. Сотрудники приложения занимают логические имена независимо друг от друга, поэтому под одним именем может лежать несколько объектов. Запрос ключом приложения БЕЗ заголовка Authorization адресует общий файл приложения; если под этим именем есть только персональные файлы сотрудников, ответ — 404 STORAGE_OBJECT_NOT_FOUND. Чтобы обратиться к файлу сотрудника, передайте его сессию в Authorization: Bearer либо используйте идентификатор объекта.

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

• Объекты
• Список объектов
• Метаданные объекта
• Загрузка