لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/storage/objects.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Objects

Storage object operations: list, download, retrieve metadata, delete, and public access.

Scope: vibe:storage | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: API key (X-Api-Key); public endpoints work without authorization

List objects

GET /v1/storage/objects

Returns completed, non-deleted storage objects with literal key-prefix filtering and cursor navigation. Without prefix, objects are ordered by descending id. With prefix, the bytewise order is ascending key, then descending id for equal keys.

A personal developer key sees all objects owned by that developer in the Bitrix24 account. An app key without a user token sees only that app's shared objects. An app key with a user token sees only the objects of the corresponding Bitrix24 employee.

Parameters

Parameter Type Default Description
Parameterlimit Typenumber Default50 DescriptionNumber of objects per page. Maximum 500; values above 500 are truncated without an error
Parameterprefix Typestring Default— DescriptionFilter by the start of the key. Example: prefix=reports/2024 returns all objects whose keys start with reports/2024
Parametercursor Typestring Default— DescriptionCursor from the previous response. Pass it unchanged. New opaque cursors are bound to the owner, prefix, and ordering mode; a legacy CUID cursor carries no such binding
ParameterwithTotal Typeboolean Defaultfalse DescriptionWhen true, adds an exact count for the complete filter without the cursor boundary. A full count can be expensive on a large set, so request it only on pages that need it

The walk is complete only when cursor is null. Do not parse or synthesize the cursor. A legacy CUID cursor is accepted only for a walk without prefix, carries no binding, and is always evaluated within the current storage access scope. When adding a prefix, restart the walk without the old cursor.

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 application

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 } = await res.json()
console.log(`On this page: ${data.length}, next page: ${cursor !== null}`)

JavaScript — OAuth application

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 } = await res.json()

Response fields

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

Field Type Description
Fielddata Typearray DescriptionArray of objects
Fielddata[].id Typestring DescriptionObject identifier (CUID)
Fielddata[].key Typestring DescriptionObject key in storage
Fielddata[].contentType Typestring DescriptionContent MIME type
Fielddata[].sizeBytes Typestring DescriptionSize in bytes. Passed as a string due to JSON limits on large numbers
Fielddata[].sha256 Typestring | null DescriptionSHA-256 hash of the content, if it was computed at upload
Fielddata[].visibility Typestring DescriptionVisibility: PRIVATE or PUBLIC
Fielddata[].uploadStatus Typestring DescriptionUpload status. In the list always COMPLETED
Fielddata[].createdAt Typestring DescriptionCreation date in ISO 8601 format
Fielddata[].deletedAt Typenull DescriptionAlways null — deleted objects do not appear in the list
Fielddata[].contentUpdatedAt Typestring (ISO 8601) DescriptionWhen the content last became current: a replacement, or the first completion of the upload. null for objects last written before this field existed
Fieldcursor Typestring | null DescriptionOpaque cursor for the next page. null if there are no more objects
Fieldtotal Typenumber DescriptionExact number of objects in the complete filter. Present only when withTotal=true

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
}

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
HTTP400 CodeSTORAGE_INVALID_LIMIT DescriptionThe limit parameter is not a positive integer
HTTP400 CodeSTORAGE_INVALID_CURSOR DescriptionA new opaque cursor is corrupted, modified, oversized, or belongs to another owner, prefix, or ordering mode; a legacy CUID cursor has an invalid shape, is oversized, or is used with prefix
HTTP401 CodeMISSING_API_KEY DescriptionAPI key not provided
HTTP403 CodeSTORAGE_SCOPE_REQUIRED DescriptionThe API key has no vibe:storage scope

For the full list of common errors, see Errors.

See also