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

List objects

GET /v1/storage/objects

Returns a list of storage objects with key-prefix filtering and cursor navigation. Only completed, non-deleted objects appear in the list. Results are sorted from newest to oldest.

Parameters

Parameter Type Default Description
limit number 50 Number of objects per page. Maximum 500; values above 500 are truncated without an error
prefix string — Filter by the start of the key. Example: prefix=reports/2024 returns all objects whose keys start with reports/2024
cursor string — Cursor to move to the next page, obtained from the cursor field of the previous response

Examples

curl — personal key

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

curl — OAuth app

Terminal 
curl "https://vibecode.bitrix24.com/v1/storage/objects?limit=10&prefix=reports/2024" \
  -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?limit=10&prefix=reports%2F2024',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { data, cursor, total } = await res.json()
console.log(`Objects: ${total}`)

JavaScript — OAuth app

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/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()

Response fields

The response does not include a success wrapper — the object is returned directly.

Field Type Description
data array Array of objects
data[].id string Object identifier (CUID)
data[].key string Object key in storage
data[].contentType string Content MIME type
data[].sizeBytes string Size in bytes. Passed as a string due to JSON limits on large numbers
data[].sha256 string | null SHA-256 hash of the content, if it was computed at upload
data[].visibility string Visibility: PRIVATE or PUBLIC
data[].uploadStatus string Upload status. In the list always COMPLETED
data[].createdAt string Creation date in ISO 8601 format
data[].deletedAt null Always null — deleted objects do not appear in the list
cursor string | null Cursor for the next page. null if there are no more objects
total number Total number of objects matching the request

Response example

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
}

Error response example

400 — invalid limit:

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

Errors

HTTP Code Description
400 STORAGE_INVALID_LIMIT The limit parameter is not a positive integer
401 MISSING_API_KEY API key not provided
403 STORAGE_SCOPE_REQUIRED The API key has no vibe:storage scope

For the full list of common errors, see Errors.

See also