# Upload

Three file upload paths into storage: a direct form for small files, a presigned PUT for browser uploads, and multipart upload for large files.

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

## Operations

- [Direct upload](./upload/direct.md) — `POST /v1/storage/objects/upload`
- [Presigned URL](./upload/presigned.md) — `POST /v1/storage/objects`
- [Complete upload](./upload/complete.md) — `POST /v1/storage/objects/complete`
- [Create multipart upload](./upload/multipart-create.md) — `POST /v1/storage/objects/multipart/create`
- [Complete multipart upload](./upload/multipart-complete.md) — `POST /v1/storage/objects/multipart/complete`
- [Abort multipart upload](./upload/multipart-abort.md) — `POST /v1/storage/objects/multipart/abort`

## Upload paths

| Path | File size | Steps |
|---|---|---|
| **A** | up to 10 MB | 1 |
| **B** | up to 5 GB | 3: create URL → PUT → complete |
| **C** | up to 5 TB | 3 + N: create → N × PUT → complete |

## Scenarios

**Choosing a path.** For files up to 10 MB use path A — a single request with a `file` field in a `multipart/form-data` form. Path B is temporarily disabled and answers `503 STORAGE_PRESIGNED_UPLOAD_DISABLED`, so anything above 10 MB goes through path C, with parallel parts of at least 5 MB each.

**Replacing content.** A live `COMPLETED` object owned by the same tuple can be replaced under its existing `key`: use Path A up to 10 MB for an app-bound or personal key, or Path C for any supported file size on an app-bound key. Both paths preserve `objectId` and `visibility`. On Path C, reads return the old content until complete publishes the new bytes. A successful complete response confirms the new version, while `502 STORAGE_BUCKET_ERROR` can mean publication happened without a confirmed result. A confirmed abort before publication preserves the old version.

**Aborting a multipart upload.** If an upload is interrupted, call `POST /v1/storage/objects/multipart/abort` — incomplete parts occupy space until an abort is confirmed. After 24 hours, the scheduler attempts to abort an incomplete session automatically. If the provider does not confirm the abort, the session is retained and releasing it requires another abort attempt or operator action.

**Visibility at upload time.** The `visibility` attribute is set once on the first upload: `PRIVATE` (default) or `PUBLIC`. On replacement, omit the field or pass the stored value. For `PUBLIC` objects the types a browser renders as a page, runs or sniffs are blocked: HTML and XHTML, SVG, JavaScript, any XML (`*/xml`, `*+xml`), XSL, `multipart/*`, `message/*`, `unknown/unknown`, `application/unknown`, `*/*`, with or without parameters — such a file returns `415 STORAGE_FORBIDDEN_CONTENT_TYPE`.

## See also

- [Storage](/docs/storage)
- [Objects](/docs/storage/objects)
- [Keys and authorization](/docs/keys-auth)