Для AI-агентов: markdown этой страницы — /docs-content/storage/objects/head.md индекс документации — /llms.txt

Метаданные объекта

HEAD /v1/storage/objects/:key

Возвращает метаданные объекта в заголовках ответа без тела. Используется для проверки существования объекта и получения его характеристик без загрузки содержимого.

Параметры

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

Примеры

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

Terminal 
curl -I "https://vibecode.bitrix24.tech/v1/storage/objects/reports%2F2024%2Fannual.pdf" \
  -H "X-Api-Key: YOUR_API_KEY"

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

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

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

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/storage/objects/reports%2F2024%2Fannual.pdf',
  {
    method: 'HEAD',
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const contentType = res.headers.get('content-type')
const size = res.headers.get('content-length')

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

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/storage/objects/reports%2F2024%2Fannual.pdf',
  {
    method: 'HEAD',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const contentType = res.headers.get('content-type')
const size = res.headers.get('content-length')

Ответ

Тело ответа отсутствует. Метаданные передаются в заголовках.

Заголовок Описание
Content-Type MIME-тип содержимого объекта
Content-Length Размер объекта в байтах
ETag Хэш содержимого в кавычках 
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 204800
ETag: "e3b0c44298fc1c149afbf4c8996fb92"

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

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

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

Ошибки

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

HTTP Код Описание
401 MISSING_API_KEY API-ключ не передан
403 STORAGE_SCOPE_REQUIRED У API-ключа нет скоупа vibe:storage
404 STORAGE_OBJECT_NOT_FOUND Объект с указанным ключом не найден
410 STORAGE_OBJECT_DELETED Объект был удалён
429 RATE_LIMITED Исчерпан бюджет чтения метаданных объекта для портала
502 STORAGE_OBJECT_HEAD_FAILED Ошибка при обращении к хранилищу
502 STORAGE_OBJECT_MISSING_IN_BUCKET Объект найден в базе данных, но отсутствует в хранилище

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

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

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