#Storage

File storage for Bitrix24 apps: upload, manage visibility, and download via temporary links.

Scope: vibe:storage | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: API key (X-Api-Key)

Authorization · Lifecycle · Upload paths · Visibility · Object key · Limits · Pricing · Quick start · Full example · Endpoints · Errors

#When to use

Suitable for:

• User avatars and app logos
• Form attachments: photos, scans, receipts
• Exports and generated reports (CSV, PDF)
• Video attachments in CRM deals
• App configuration backups
• Intermediate files in a data-processing pipeline

Not suitable for:

• Publishing files to the Bitrix24 account Drive — use the Drive section for that; storage is isolated per app and is not part of the Bitrix24 account's drive tree
• Storing secrets and keys — use server environment variables
• App logging and audit
• Scenarios not tied to an app — storage is always isolated per key

#Documentation sections

#Authorization

All requests to /v1/storage/* require an API key in the X-Api-Key header with the vibe:storage scope.

New keys receive the vibe:storage scope automatically. If a key was created before it existed — add the scope in the API Keys section of your account.

A missing scope returns 403 STORAGE_SCOPE_REQUIRED on any /v1/storage/* call.

Key types

Management keys (vibe_live_*) are not suitable for /v1/storage/* — they have no Bitrix24 account binding. Any call returns 403 STORAGE_REQUIRES_PORTAL_BINDING.

Isolation. Objects are isolated per key owner: a key from one Bitrix24 account cannot access objects of another Bitrix24 account — such a request returns 404 STORAGE_OBJECT_NOT_FOUND, not 403, so as not to reveal the existence of another Bitrix24 account's resources.

#Object lifecycle

PENDING      — created, awaiting file upload (paths B and C)
    │
    ▼ (path A → immediately COMPLETED)
COMPLETED    — file uploaded, available for reading
    │
    ▼ (DELETE)
deletedAt    — soft delete: read → 410; data retained for another 30 days
    │
    ▼ (+30 days, scheduler)
deleted      — data erased from storage

Direct upload (path A) creates the object immediately in the COMPLETED state. Paths B and C create the object in the PENDING state — until /complete is called.

Objects in the PENDING state without completion are removed by a background scheduler after 24 hours.

#Upload paths

A detailed description of each path — Upload.

#Visibility and access

Each object has a visibility attribute:

• PRIVATE (default) — download via an authorized GET /v1/storage/objects/:key request, which returns a 302 redirect to a presigned URL valid for 10 minutes.
• PUBLIC — additionally available via a permanent URL of the form https://vibecode.bitrix24.com/v1/public-storage/:portalId/:objectId without authorization.

For PUBLIC objects, serving files with content types text/html, application/javascript, application/x-javascript, image/svg+xml is blocked. An attempt to upload a file with such a type at visibility=PUBLIC returns 415 STORAGE_FORBIDDEN_CONTENT_TYPE.

Anonymous access via public-storage is enabled on the Bitrix24 account side and is off by default. While it is off, requests to the public URL return 503 STORAGE_PUBLIC_GET_DISABLED_FOR_PORTAL.

A permanent source for external tools. The presigned URL from GET /v1/storage/objects/:key is valid for 10 minutes and requires an X-Api-Key header, so it does not work as a permanent source for tools that do not send authorization headers — importing data into spreadsheets, report schedulers, external dashboards. For that scenario, set the object to PUBLIC and use its permanent URL https://vibecode.bitrix24.com/v1/public-storage/:portalId/:objectId, which is served without authorization while anonymous access is enabled on the Bitrix24 account side. For PUBLIC reports, content types such as text/csv, application/json, and similar are suitable. The types text/html, application/javascript, and image/svg+xml are blocked.

#Object key

The object key is a unique identifier within the namespace bound to your key (the owner's personal namespace or the app's namespace). Rules:

• Length: 1–1024 characters.
• Allowed characters: a-z, A-Z, 0-9, ., _, /, -.
• Cannot start with / or ..
• Cannot contain the sequence ...
• The / character is a path separator, used for grouping by prefix.

In URL path parameters, slashes in the key must be encoded: encodeURIComponent('users/42/report.csv') returns 'users%2F42%2Freport.csv'.

#Limits

#Pricing

Storage runs on a pay-as-you-go scheme. The platform charges for three resources.

Rates are set by the platform and differ from instance to instance. The current values are returned in the storage block of the GET /v1/me response.

At a zero balance, write requests are blocked for 24 hours. Reading objects continues to work. Topping up the balance unblocks writing immediately.

Current usage and a cost forecast are in the storage block of the GET /v1/me response. The Bitrix24 account owner also sees aggregate spending across apps and can export a report on the Storage page in the Bitrix24 account admin panel.

#Use in AI agents

Storage is available to AI models and agents without reading this page:

• The storage block in the GET /v1/me response — storage state, rates, upload paths, and the list of endpoints.
• The vibe_storage_* tools of the MCP server (upload, presigned links, list, delete, spending control) — see MCP for AI.

#Quick start

Upload a file (path A):

curl -X POST https://vibecode.bitrix24.com/v1/storage/objects/upload \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "key=reports/march.csv" \
  -F "visibility=PRIVATE" \
  -F "file=@march.csv;type=text/csv"

Get a download link:

curl -I \
  -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/storage/objects/reports%2Fmarch.csv"
# HTTP/1.1 302 Found
# Location: <temporary link to the object, valid for 10 minutes>

#Full example

Full cycle: upload → list → get link → delete.

const KEY = 'YOUR_API_KEY'
const BASE = 'https://vibecode.bitrix24.com/v1'

const form = new FormData()
form.append('key', 'users/42/report.csv')
form.append('visibility', 'PRIVATE')
form.append('file', new Blob(['id,name\n1,Alice\n2,Bob'], { type: 'text/csv' }), 'report.csv')

const uploadRes = await fetch(`${BASE}/storage/objects/upload`, {
  method: 'POST',
  headers: { 'X-Api-Key': KEY },
  body: form,
})
const { object } = await uploadRes.json()
console.log('Uploaded:', object.key, '| uploadStatus:', object.uploadStatus)

const listRes = await fetch(`${BASE}/storage/objects?prefix=users/42`, {
  headers: { 'X-Api-Key': KEY },
})
const { data, total } = await listRes.json()
console.log('Objects:', total, '| first:', data[0]?.key)

const getRes = await fetch(`${BASE}/storage/objects/${encodeURIComponent(object.key)}`, {
  headers: { 'X-Api-Key': KEY },
  redirect: 'manual',
})
const downloadUrl = getRes.headers.get('location')
console.log('Link (10 min):', downloadUrl)

const delRes = await fetch(`${BASE}/storage/objects/${encodeURIComponent(object.key)}`, {
  method: 'DELETE',
  headers: { 'X-Api-Key': KEY },
})
const { object: deleted } = await delRes.json()
console.log('Deleted:', deleted.key, '| deletedAt:', deleted.deletedAt)

#Common scenarios

#Large file via multipart upload

Uploading a large file in parts with cancellation on error (to avoid paying for unfinished parts):

const KEY = 'YOUR_API_KEY'
const BASE = 'https://vibecode.bitrix24.com/v1'
const PART_SIZE = 8 * 1024 * 1024 // 8 MB

// file — File or Blob, e.g. from <input type="file">
const init = await fetch(`${BASE}/storage/objects/multipart/create`, {
  method: 'POST',
  headers: { 'X-Api-Key': KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    key: 'videos/demo.mp4',
    contentType: 'video/mp4',
    totalSize: file.size,
    partSize: PART_SIZE,
    visibility: 'PRIVATE',
  }),
})
const { objectId, parts } = await init.json()

try {
  const uploaded = []
  for (const part of parts) {
    const chunk = file.slice((part.partNumber - 1) * PART_SIZE, part.partNumber * PART_SIZE)
    const res = await fetch(part.uploadUrl, { method: 'PUT', body: chunk })
    uploaded.push({ partNumber: part.partNumber, etag: res.headers.get('etag') })
  }
  const done = await fetch(`${BASE}/storage/objects/multipart/complete`, {
    method: 'POST',
    headers: { 'X-Api-Key': KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ objectId, parts: uploaded }),
  })
  const { object } = await done.json()
  console.log('Uploaded:', object.key, object.sizeBytes)
} catch (err) {
  await fetch(`${BASE}/storage/objects/multipart/abort`, {
    method: 'POST',
    headers: { 'X-Api-Key': KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ objectId }),
  })
  throw err
}

#Bulk cleanup by prefix

Deleting all of a user's files when they are disabled: paginated iteration by prefix and deletion of each object.

const KEY = 'YOUR_API_KEY'
const BASE = 'https://vibecode.bitrix24.com/v1'

async function deleteByPrefix(prefix) {
  let cursor = null
  let removed = 0
  do {
    const url = new URL(`${BASE}/storage/objects`)
    url.searchParams.set('prefix', prefix)
    url.searchParams.set('limit', '500')
    if (cursor) url.searchParams.set('cursor', cursor)

    const page = await fetch(url, { headers: { 'X-Api-Key': KEY } })
    const { data, cursor: next } = await page.json()

    for (const obj of data) {
      await fetch(`${BASE}/storage/objects/${encodeURIComponent(obj.key)}`, {
        method: 'DELETE',
        headers: { 'X-Api-Key': KEY },
      })
      removed++
    }
    cursor = next
  } while (cursor)
  return removed
}

const count = await deleteByPrefix('users/42/')
console.log('Objects deleted:', count)

#Endpoint reference

#Upload

#Objects

#Public access

#Error codes

General API error codes — Error codes.

#See also

• Upload
• Objects
• Keys and authorization
• Scopes