Для AI-агентов: markdown этой страницы — /docs-content/storage/objects/list.md индекс документации — /llms.txt

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

GET /v1/storage/objects

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

Личный ключ разработчика видит все объекты своего владельца на портале. Ключ приложения без пользовательского токена видит только общие объекты этого приложения. Ключ приложения с пользовательским токеном видит только объекты соответствующего сотрудника Битрикс24.

Параметры

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

Обход завершён только при cursor: null. Не разбирайте курсор и не вычисляйте его самостоятельно. Старый курсор в виде CUID принимается только для обхода без prefix, не содержит привязки и всегда применяется внутри текущей области доступа к хранилищу. При добавлении prefix начните обход заново без старого курсора.

Примеры

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

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

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

Terminal 
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 } = await res.json()
console.log(`На странице: ${data.length}, следующая страница: ${cursor !== null}`)

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 } = 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 Точное количество объектов по всему фильтру. Поле присутствует только при withTotal=true

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

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
}

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

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

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

Ошибки

HTTP Код Описание
400 STORAGE_INVALID_LIMIT Параметр limit не является положительным целым числом
400 STORAGE_INVALID_CURSOR Новый непрозрачный курсор повреждён, изменён, слишком велик либо относится к другому владельцу, префиксу или порядку; старый CUID-курсор имеет неверный формат, слишком велик либо используется вместе с prefix
401 MISSING_API_KEY API-ключ не передан
403 STORAGE_SCOPE_REQUIRED У API-ключа нет скоупа vibe:storage

Полный список общих ошибок — Ошибки.

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