## Прямая загрузка файла `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`. | Параметр | Тип | Обяз. | По умолч. | Описание | |----------|-----|:-----:|-----------|---------| | `file` | file | да | — | Бинарный файл размером не более 10 МБ. MIME-тип определяется из заголовка `Content-Type` части формы. Если заголовок отсутствует, используется `application/octet-stream` | | `key` | string | да | — | Логический ключ объекта: от 1 до 1024 символов, допустимы `a-z`, `A-Z`, `0-9`, `.`, `_`, `/`, `-`. Не начинать с `/` или `.`, не содержать `..` | | `visibility` | string | нет | `PRIVATE` | Видимость объекта: `PRIVATE` или `PUBLIC`. У **нового** объекта пропущенное поле означает `PRIVATE`. При **замене** существующего объекта видимость не меняется: поле можно не передавать либо передать текущее значение | ## Примеры ### curl — личный ключ ```bash 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-приложение ```bash 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 — личный ключ ```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-приложение ```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_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, body: formData, }) const { object } = await res.json() ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `object.id` | string | Идентификатор объекта | | `object.key` | string | Логический ключ объекта | | `object.contentType` | string | MIME-тип файла | | `object.sizeBytes` | string | Размер файла в байтах (строка) | | `object.sha256` | string | SHA-256 хеш файла. При прямой загрузке вычисляется всегда | | `object.visibility` | string | Видимость: `PRIVATE` или `PUBLIC` | | `object.uploadStatus` | string | Статус загрузки: `COMPLETED` | | `object.createdAt` | string | Дата создания (ISO 8601) | | `object.deletedAt` | string | Дата удаления или `null` | | `object.contentUpdatedAt` | string (ISO 8601) | Когда содержимое последний раз стало актуальным: замена или первое завершение загрузки. Не двигается служебными обновлениями. `null` у объектов, записанных до появления поля | ## Пример ответа ```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-тип, недопустимый из соображений межсайтового выполнения скриптов: ```json { "success": false, "error": { "code": "STORAGE_FORBIDDEN_CONTENT_TYPE", "message": "Content-Type text/html is not allowed for PUBLIC objects (XSS-prone)" } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 403 | `STORAGE_SCOPE_REQUIRED` | API-ключу не хватает скоупа `vibe:storage` | | 401 | `STORAGE_NO_AUTH_CONTEXT` | Запрос выполнен без авторизации | | 400 | `STORAGE_FILE_REQUIRED` | Не передано поле `file` | | 400 | `STORAGE_KEY_REQUIRED` | Не передано поле `key` | | 400 | `STORAGE_INVALID_KEY` | Значение `key` нарушает правила формата | | 400 | `STORAGE_INVALID_VISIBILITY` | Недопустимое значение `visibility` | | 400 | `STORAGE_VISIBILITY_MISMATCH` | Замена содержимого не может изменить видимость объекта. Не передавайте поле или передайте текущее значение — оно указано в сообщении об ошибке | | 409 | `STORAGE_KEY_DELETED` | Объект под этим ключом удалён и держит имя до физической уборки (30 дней). Используйте другой ключ | | 409 | `STORAGE_MULTIPART_IN_PROGRESS` | У объекта идёт составная загрузка — завершите или оборвите её | | 409 | `STORAGE_UPLOAD_PENDING` | По ключу выдана предподписанная ссылка, и загрузка ещё не подтверждена | | 409 | `STORAGE_KEY_OWNED_ELSEWHERE` | Логическое имя занято другим объектом приложения (общие и персональные файлы хранятся по разным адресам) | | 409 | `STORAGE_KEY_CONFLICT` | Конфликт состояния объекта либо конкурентная прямая загрузка (путь A) с ключом приложения не получила право записи в пределах 60 секунд или лимита конкурентности. До подтверждения объектное хранилище не затрагивается; повторите весь запрос. Для личного ключа (`appId = null`) и путей B/C сериализация не обещана | | 400 | `STORAGE_MULTIPART_PARSE_FAILED` | Не удалось разобрать тело запроса как `multipart/form-data` | | 413 | `STORAGE_UPLOAD_TOO_LARGE` | Файл превышает 10 МБ — используйте составную загрузку (путь B временно отключён) | | 415 | `STORAGE_FORBIDDEN_CONTENT_TYPE` | Для `PUBLIC`-объектов запрещены типы `text/html`, `application/javascript`, `application/x-javascript`, `image/svg+xml` | | 402 | `BILLING_INSUFFICIENT` | Недостаточно средств на балансе | | 503 | `STORAGE_FEATURE_DISABLED` | Хранилище отключено для портала | | 502 | `STORAGE_BUCKET_ERROR` | Ошибка при взаимодействии с хранилищем | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности **Файлы крупнее 10 МБ.** Путь B временно отключён и отвечает `503 STORAGE_PRESIGNED_UPLOAD_DISABLED`, поэтому всё, что больше 10 МБ, загружайте [составной загрузкой](/docs/storage/upload/multipart-create) (Путь C). **Проверка типа для `PUBLIC`-объектов.** Проверка выполняется по заявленному `Content-Type` части формы до записи файла — при нарушении запрос отклоняется без обращения к хранилищу. ## Смотрите также - [Загрузка](/docs/storage/upload) - [Создать предподписанный URL](/docs/storage/upload/presigned) - [Подтвердить загрузку](/docs/storage/upload/complete) - [Составная загрузка](/docs/storage/upload/multipart-create) - [Хранилище](/docs/storage)