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. Use it to check whether an object exists and get its properties without downloading the content.

Parameters

Parameter Type Required Description
Parameterkey (path) Typestring Requiredyes DescriptionObject 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 fields

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

Header Description
HeaderContent-Type DescriptionThe object's content MIME type
HeaderContent-Length DescriptionThe object's size in bytes
HeaderETag DescriptionContent hash in quotes

Response example

http 
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 303
ETag: "dbaa5d4c5e4a709133830a8facd9fec8"

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. The current limit is returned in x-ratelimit-limit; after a 429, retry after the delay in Retry-After.

HTTP Code Description
HTTP401 CodeMISSING_API_KEY DescriptionAPI key not passed
HTTP403 CodeSTORAGE_SCOPE_REQUIRED DescriptionThe API key has no vibe:storage scope
HTTP404 CodeSTORAGE_OBJECT_NOT_FOUND DescriptionNo object found with the given key
HTTP410 CodeSTORAGE_OBJECT_DELETED DescriptionThe object was deleted
HTTP429 CodeRATE_LIMITED DescriptionThe portal object-metadata read budget is exhausted
HTTP502 CodeSTORAGE_OBJECT_HEAD_FAILED DescriptionError accessing storage
HTTP502 CodeSTORAGE_OBJECT_MISSING_IN_BUCKET DescriptionThe object exists in the database but is missing from storage

For the full list of general errors, see Errors.

  • An app key with no employee session sees only the app-shared file. Employees of an app use logical names independently of each other, so multiple objects can share the same logical 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