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

Public object metadata

HEAD /v1/public-storage/:portalId/:objectId

Returns the metadata of a publicly accessible object in the response headers without transferring the content. No API key is required — the endpoint is anonymous. Anonymous access is enabled separately at the Bitrix24 account level; off by default.

Parameters

Parameter Type Req. Description
portalId (path) string (UUID) yes The Bitrix24 portal identifier in Vibecode. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Obtain via GET /v1/me with a management key — the data.portals[n].id field
objectId (path) string (CUID) yes Internal object identifier (the id field from write and list responses)

Examples

No key required. Both examples are sent without authorization headers — this is an anonymous endpoint.

curl

Terminal 
curl -I "https://vibecode.bitrix24.com/v1/public-storage/YOUR_PORTAL_ID/YOUR_OBJECT_ID"

JavaScript

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/public-storage/YOUR_PORTAL_ID/YOUR_OBJECT_ID',
  { method: 'HEAD' }
)
if (res.ok) {
  console.log('MIME type:', res.headers.get('content-type'))
  console.log('Size:', res.headers.get('content-length'))
}

Response

The behavior depends on the state of anonymous access in the Bitrix24 account:

Anonymous access enabled in the Bitrix24 account. The server returns 200 OK with headers:

Header Value
Content-Type The object's content MIME type
Content-Length The object's size in bytes
Cache-Control private, no-store

There is no response body.

Anonymous access disabled in the Bitrix24 account (the current state of the test environment): 503 STORAGE_PUBLIC_GET_DISABLED_FOR_PORTAL.

Error response example

503 — anonymous access disabled in the Bitrix24 account:

JSON 
{
  "success": false,
  "error": {
    "code": "STORAGE_PUBLIC_GET_DISABLED_FOR_PORTAL",
    "message": "Public storage GET is disabled for this portal"
  }
}

Errors

HTTP Code Description
404 STORAGE_OBJECT_NOT_FOUND Object not found, has PRIVATE visibility, belongs to another portal, or objectId does not match any object
410 STORAGE_OBJECT_DELETED The object was deleted
429 STORAGE_RATE_LIMIT_EXCEEDED Exceeded the limit of 60 requests per minute from a single IP address
503 STORAGE_PUBLIC_GET_DISABLED_FOR_PORTAL Anonymous access is disabled in this portal
503 STORAGE_FEATURE_DISABLED Storage is temporarily unavailable on the platform

The full list of general API errors — Errors.

Known specifics

  • Anonymous access is enabled separately. An object with PUBLIC visibility does not automatically become available through this endpoint — the Bitrix24 account administrator must enable anonymous access in the storage settings.
  • objectId is the internal identifier, not the logical key. Use the id field from the upload response (POST /v1/storage/objects/upload) or from the object list.
  • The Content-Length header contains the object's real size from the database — not the length of the serialized response.

See also