## Список объектов

`GET /v1/storage/objects`

Возвращает список объектов хранилища с фильтрацией по префиксу ключа и навигацией по курсору. В список попадают только завершённые, не удалённые объекты. Результаты отсортированы от новых к старым.

## Параметры

| Параметр | Тип | По умолч. | Описание |
|----------|-----|-----------|---------|
| `limit` | number | `50` | Количество объектов на страницу. Максимум 500; значения выше 500 усекаются без ошибки |
| `prefix` | string | — | Фильтр по началу ключа. Пример: `prefix=reports/2024` вернёт все объекты, ключи которых начинаются с `reports/2024` |
| `cursor` | string | — | Курсор для перехода на следующую страницу, полученный из поля `cursor` предыдущего ответа |

## Примеры

### curl — личный ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/storage/objects?limit=10&prefix=reports/2024" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/storage/objects?limit=10&prefix=reports/2024" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/storage/objects?limit=10&prefix=reports%2F2024',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { data, cursor, total } = await res.json()
console.log(`Объектов: ${total}`)
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/storage/objects?limit=10&prefix=reports%2F2024',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { data, cursor, total } = await res.json()
```

## Поля ответа

Ответ не содержит обёртку `success` — возвращается объект напрямую.

| Поле | Тип | Описание |
|------|-----|---------|
| `data` | array | Массив объектов |
| `data[].id` | string | Идентификатор объекта (CUID) |
| `data[].key` | string | Ключ объекта в хранилище |
| `data[].contentType` | string | MIME-тип содержимого |
| `data[].sizeBytes` | string | Размер в байтах. Передаётся строкой из-за ограничений JSON на большие числа |
| `data[].sha256` | string \| null | SHA-256 хэш содержимого, если был вычислен при загрузке |
| `data[].visibility` | string | Видимость: `PRIVATE` или `PUBLIC` |
| `data[].uploadStatus` | string | Статус загрузки. В списке всегда `COMPLETED` |
| `data[].createdAt` | string | Дата создания в формате ISO 8601 |
| `data[].deletedAt` | null | Всегда `null` — удалённые объекты в список не попадают |
| `data[].contentUpdatedAt` | string (ISO 8601) | Когда содержимое последний раз стало актуальным: замена или первое завершение загрузки. `null` у объектов, записанных до появления поля |
| `cursor` | string \| null | Курсор для следующей страницы. `null`, если объектов больше нет |
| `total` | number | Общее количество объектов, соответствующих запросу |

## Пример ответа

```json
{
  "data": [
    {
      "id": "cmabcdef1234567890abcdef",
      "key": "reports/2024/annual.pdf",
      "contentType": "application/pdf",
      "sizeBytes": "204800",
      "sha256": null,
      "visibility": "PRIVATE",
      "uploadStatus": "COMPLETED",
      "createdAt": "2024-06-15T10:30:00.000Z",
      "deletedAt": null
    }
  ],
  "cursor": null,
  "total": 1
}
```

## Пример ответа при ошибке

400 — некорректный `limit`:

```json
{
  "success": false,
  "error": {
    "code": "STORAGE_INVALID_LIMIT",
    "message": "limit must be a positive integer"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `STORAGE_INVALID_LIMIT` | Параметр `limit` не является положительным целым числом |
| 401 | `MISSING_API_KEY` | API-ключ не передан |
| 403 | `STORAGE_SCOPE_REQUIRED` | У API-ключа нет скоупа `vibe:storage` |

Полный список общих ошибок — [Ошибки](/docs/errors).

## Смотрите также

- [Объекты](/docs/storage/objects)
- [Скачать объект](/docs/storage/objects/get)
- [Метаданные объекта](/docs/storage/objects/head)
- [Загрузка](/docs/storage/upload)