Direct file upload

POST /v1/storage/objects/upload

Uploads a file up to 10 MB in a single multipart/form-data request — the server accepts the file and returns the resulting storage object.

Uploading again under the same key replaces the object content. This also applies to a soft-deleted object when it belongs to the same owner tuple, has COMPLETED status, and has no open multipart session. The row is revived with the same object.id, createdAt, key, physical address, owner tuple, and visibility; deletedAt is cleared, while sizeBytes, sha256, contentType, and contentUpdatedAt are updated to match the new bytes.

This does not restore the deleted content: Path A writes new bytes over the old ones. For a PUBLIC object, a previously issued anonymous URL with the same object.id starts working again and serves the new bytes. To replace or revive an object, omit visibility or pass the stored value — visibility cannot change (STORAGE_VISIBILITY_MISMATCH). Deleted PENDING rows and rows with a multipart session stay occupied and return 409 STORAGE_KEY_DELETED.

Replacement and revival work the same way for an app-bound key and for a personal developer key: uploading again under the same key does not create a second object.

For Path A direct uploads, concurrent requests to the same physical address run one at a time. A request waits for its turn for no more than 60 seconds; if safe write ownership cannot be confirmed, the server returns 409 STORAGE_KEY_CONFLICT before writing to object storage. Retry the entire request. The guarantee also covers a personal key (appId = null). Path C serializes every key, but replaces a live object only for an app-bound key; it accepts a personal key after explicit DELETE. Path B is excluded.

Request fields (body)

The request body must be in multipart/form-data format.

Examples

curl — personal key

curl -X POST https://vibecode.bitrix24.com/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 application

curl -X POST https://vibecode.bitrix24.com/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 — personal key

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.com/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 application

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.com/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()

Response fields

Response example

{
  "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
  }
}

Error response example

415 — the request passed a MIME type that is not allowed for PUBLIC objects because of cross-site scripting risks:

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

Errors

Full list of common API errors — Errors.

Known specifics

Files larger than 10 MB. Path B is temporarily disabled and answers 503 STORAGE_PRESIGNED_UPLOAD_DISABLED, so upload anything above 10 MB with multipart upload (Path C).

Type check for PUBLIC objects. The check runs against the declared Content-Type of the form part before the file is written — if it fails, the request is rejected without accessing storage.

See also

• Upload
• Create presigned URL
• Complete upload
• Multipart upload
• Storage