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 completed (COMPLETED) publicly accessible object in the response headers without transferring the content. PENDING objects are not served and return 404 STORAGE_OBJECT_NOT_FOUND without the metadata headers of a successful response. No API key is required — the endpoint is anonymous. Anonymous access is enabled separately at the Bitrix24 account level and is off by default.

Parameters

Parameter Type Required Description
ParameterportalId (path) Typestring (UUID) Requiredyes DescriptionThe Bitrix24 portal identifier in Vibecode. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Source: GET /v1/me — the data.portalId field for vibe_api_ and vibe_app_ keys, data.portals[n].id for a vibe_live_ management key
ParameterobjectId (path) Typestring (CUID) Requiredyes DescriptionInternal object identifier: the object.id field from the Direct file upload response or data[].id from the List objects response

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 fields

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

Anonymous access enabled in the Bitrix24 account. For a completed PUBLIC object, the server returns 200 OK with the following headers:

Header Value
HeaderContent-Type ValueThe object's content MIME type
HeaderContent-Length ValueThe object's size in bytes
HeaderCache-Control Valueprivate, no-store

There is no response body.

Anonymous access disabled in the Bitrix24 account (the default for a new Bitrix24 account): 503 STORAGE_PUBLIC_GET_DISABLED_FOR_PORTAL. It is enabled by the Bitrix24 account administrator.

Response example

Anonymous access is enabled in the Bitrix24 account and the object is PUBLIC:

http 
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 303
Cache-Control: private, no-store

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
HTTP404 CodeSTORAGE_OBJECT_NOT_FOUND DescriptionThe upload is incomplete (PENDING), the object is missing, has PRIVATE visibility, belongs to another portal, or objectId does not match any object
HTTP410 CodeSTORAGE_OBJECT_DELETED DescriptionThe completed object was deleted
HTTP429 CodeSTORAGE_RATE_LIMIT_EXCEEDED DescriptionExceeded the limit of 60 requests per minute from a single IP address. The current limit is returned in the x-ratelimit-limit header
HTTP503 CodeSTORAGE_PUBLIC_GET_DISABLED_FOR_PORTAL DescriptionAnonymous access is disabled in this portal
HTTP503 CodeSTORAGE_FEATURE_DISABLED DescriptionStorage is temporarily unavailable on the platform

For the full list of general API errors, see Errors.

Known specifics

  • Anonymous access is enabled separately. Even a completed 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 object.id field from the Direct file upload response or data[].id from the List objects response.
  • The Content-Length header contains the object's real size from the database — not the length of the serialized response.

See also