Загрузка

Три пути загрузки файлов в хранилище: прямая форма для небольших файлов, предподписанный PUT для загрузки из браузера и составная загрузка для крупных файлов.

Скоуп: vibe:storage | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: API-ключ (X-Api-Key)

Прямая загрузка файла

POST /v1/storage/objects/upload

Загружает файл до 10 МБ одним запросом в формате multipart/form-data — сервер принимает файл и возвращает готовый объект хранилища.

Повторная загрузка на тот же key заменяет содержимое объекта. Идентификатор объекта (object.id) при этом сохраняется, поэтому ранее выданные ссылки продолжают работать; sizeBytes, sha256, contentType и contentUpdatedAt обновляются под новые байты. Чтобы заменить содержимое, поле visibility не передавайте либо передайте текущее значение объекта — иным значением сменить видимость нельзя (STORAGE_VISIBILITY_MISMATCH).

⚠️ Замена работает для ключа приложения (OAuth-app ключ, привязанный к приложению). У личного ключа разработчика без привязки к приложению повторная загрузка на тот же key по-прежнему создаёт новый объект со своим id, а прежний остаётся в списке и продолжает учитываться в счёте — это известное поведение, оно чинится отдельно.

Для прямой загрузки по пути A с ключом, привязанным к приложению, конкурентные запросы к одному физическому адресу выполняются по очереди. Запрос ждёт свою очередь не более 60 секунд; если безопасно получить право записи не удалось, сервер возвращает 409 STORAGE_KEY_CONFLICT до записи в объектное хранилище. Повторите весь запрос. Эта гарантия не распространяется на личные ключи без привязки к приложению (appId = null) и пути B/C.

Поля запроса (body)

Тело запроса должно быть в формате multipart/form-data.

Примеры

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

curl -X POST https://vibecode.bitrix24.tech/v1/storage/objects/upload \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@avatar.png;type=image/png" \
  -F "key=users/42/avatar.png" \
  -F "visibility=PRIVATE"

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

curl -X POST https://vibecode.bitrix24.tech/v1/storage/objects/upload \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -F "file=@avatar.png;type=image/png" \
  -F "key=users/42/avatar.png" \
  -F "visibility=PRIVATE"

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

const formData = new FormData()
formData.append('file', fileInput.files[0])
formData.append('key', 'users/42/avatar.png')
formData.append('visibility', 'PRIVATE')

const res = await fetch('https://vibecode.bitrix24.tech/v1/storage/objects/upload', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
  body: formData,
})

if (!res.ok) {
  const { error } = await res.json()
  console.error(error.code, error.message)
  return
}
const { object } = await res.json()
console.log('Object ID:', object.id)

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

const formData = new FormData()
formData.append('file', fileInput.files[0])
formData.append('key', 'users/42/avatar.png')
formData.append('visibility', 'PRIVATE')

const res = await fetch('https://vibecode.bitrix24.tech/v1/storage/objects/upload', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
  body: formData,
})

const { object } = await res.json()

Поля ответа

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

{
  "object": {
    "id": "cmpf9b1gp003omr0zkc0qjojn",
    "key": "users/42/avatar.png",
    "contentType": "image/png",
    "sizeBytes": "20480",
    "sha256": "10068f1908d45621f11b50a1d23ddc0720a669c15f45a43d883604e7793537cd",
    "visibility": "PRIVATE",
    "uploadStatus": "COMPLETED",
    "createdAt": "2026-05-21T08:56:32.809Z",
    "deletedAt": null
  }
}

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

415 — для PUBLIC-объектов передан MIME-тип, недопустимый из соображений межсайтового выполнения скриптов:

{
  "success": false,
  "error": {
    "code": "STORAGE_FORBIDDEN_CONTENT_TYPE",
    "message": "Content-Type text/html is not allowed for PUBLIC objects (XSS-prone)"
  }
}

Ошибки

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

Известные особенности

Файлы крупнее 10 МБ. Путь B временно отключён и отвечает 503 STORAGE_PRESIGNED_UPLOAD_DISABLED, поэтому всё, что больше 10 МБ, загружайте составной загрузкой (Путь C).

Проверка типа для PUBLIC-объектов. Проверка выполняется по заявленному Content-Type части формы до записи файла — при нарушении запрос отклоняется без обращения к хранилищу.

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

• Загрузка
• Создать предподписанный URL
• Подтвердить загрузку
• Составная загрузка
• Хранилище