For AI agents: markdown of this page — /docs-content-en/storage/objects/head.md documentation index — /llms.txt

Object metadata

HEAD /v1/storage/objects/:key

Returns the object's metadata in the response headers without a body. Used to check an object's existence and retrieve its characteristics without downloading the content.

Parameters

Parameter Type Description
key string Object key. The / characters in the key must be encoded: users%2F42%2Favatar.png

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/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 application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/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')

Response

There is no response body. Metadata is passed in the headers.

Header Description
Content-Type The object's content MIME type
Content-Length The object's size in bytes
ETag Content hash in quotes 
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 204800
ETag: "e3b0c44298fc1c149afbf4c8996fb92"

Error response example

404 — object not found:

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

Errors

The method is limited to 600 requests per minute per Bitrix24 account. All API keys of the account share this budget, and the limit is divided across active platform replicas. The effective value arrives in x-ratelimit-limit; after a 429, retry after the delay in Retry-After.

HTTP Code Description
401 MISSING_API_KEY API key not passed
403 STORAGE_SCOPE_REQUIRED The API key has no vibe:storage scope
404 STORAGE_OBJECT_NOT_FOUND No object found with the given key
410 STORAGE_OBJECT_DELETED The object was deleted
429 RATE_LIMITED The account object-metadata read budget is exhausted
502 STORAGE_OBJECT_HEAD_FAILED Error accessing storage
502 STORAGE_OBJECT_MISSING_IN_BUCKET The object is found in the database but absent from storage

The full list of general errors — Errors.

  • An app key with no employee session sees only the app-shared file. Employees of an app claim logical names independently of each other, so several objects may hold one name. A request made with an app key and NO Authorization header addresses the app-shared file; if the name is held solely by per-employee files, the response is 404 STORAGE_OBJECT_NOT_FOUND. To reach an employee's file, pass that employee's session in Authorization: Bearer, or address the object by its identifier.

See also