## 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 |
|----------|-----|:-----:|---------|
| `key` (path) | string | yes | Object key. The `/` characters in the key must be encoded: `users%2F42%2Favatar.png` |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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 |
|-----------|---------|
| `Content-Type` | The object's content MIME type |
| `Content-Length` | The object's size in bytes |
| `ETag` | Content 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 |
|------|-----|---------|
| 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 portal object-metadata read budget is exhausted |
| 502 | `STORAGE_OBJECT_HEAD_FAILED` | Error accessing storage |
| 502 | `STORAGE_OBJECT_MISSING_IN_BUCKET` | The object exists in the database but is missing from storage |

For the full list of general errors, see [Errors](/docs/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

- [Objects](/docs/storage/objects)
- [List objects](/docs/storage/objects/list)
- [Download object](/docs/storage/objects/get)
- [Upload](/docs/storage/upload)