## Загрузить файл

`POST /v1/files/upload`

Загружает файл на Диск Битрикс24. Содержимое передаётся в кодировке Base64 в теле JSON-запроса. Для загрузки необходимо указать папку (`folderId`) или хранилище (`storageId`).

## Поля запроса

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|---------|
| `filename` | string | да | Имя файла с расширением, например `report.pdf` |
| `content` | string | да | Содержимое файла в кодировке Base64 |
| `folderId` | number | условно | ID папки-назначения. Список папок: `GET /v1/folders`. Обязателен, если не указан `storageId` |
| `storageId` | number | условно | ID хранилища (загрузка в корень). Список хранилищ: `GET /v1/storages`. Обязателен, если не указан `folderId` |

Необходимо указать один из двух параметров: `folderId` или `storageId`.

## Примеры

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

```bash
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folderId":27,"filename":"report.txt","content":"SGVsbG8gV29ybGQ="}' \
  https://vibecode.bitrix24.tech/v1/files/upload
```

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

```bash
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folderId":27,"filename":"report.txt","content":"SGVsbG8gV29ybGQ="}' \
  https://vibecode.bitrix24.tech/v1/files/upload
```

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

```javascript
const content = Buffer.from('Hello World').toString('base64')

const res = await fetch('https://vibecode.bitrix24.tech/v1/files/upload', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    folderId: 27,
    filename: 'report.txt',
    content,
  }),
})
const body = await res.json()
console.log(body.data.id, body.data.downloadUrl)
```

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

```javascript
const content = Buffer.from('Hello World').toString('base64')

const res = await fetch('https://vibecode.bitrix24.tech/v1/files/upload', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    folderId: 27,
    filename: 'report.txt',
    content,
  }),
})
const body = await res.json()
console.log(body.data.id, body.data.downloadUrl)
```

### Загрузка в корень хранилища

Если нужно загрузить файл в корень хранилища, а не в папку, передайте `storageId` вместо `folderId`. ID хранилища доступен в поле `id` из `GET /v1/storages`, корневая папка — в поле `rootFolderId`.

```bash
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"storageId":1,"filename":"backup.txt","content":"SGVsbG8gV29ybGQ="}' \
  https://vibecode.bitrix24.tech/v1/files/upload
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.id` | number | ID созданного файла |
| `data.name` | string | Имя файла |
| `data.code` | string \| null | Символьный код файла |
| `data.storageId` | number | ID хранилища, в котором находится файл |
| `data.type` | string | Тип объекта — всегда `"file"` |
| `data.folderId` | number | ID папки, в которой находится файл |
| `data.deletedType` | number | Тип удаления: `0` — не удалён |
| `data.globalContentVersion` | number | Версия содержимого файла |
| `data.fileId` | number | ID файла во внутреннем хранилище Битрикс24 |
| `data.size` | number | Размер файла в байтах |
| `data.createdBy` | number | ID пользователя, создавшего файл. Список: `GET /v1/users` |
| `data.updatedBy` | number | ID пользователя, изменившего файл последним |
| `data.deletedBy` | number \| null | ID удалившего файл или `null`, если файл не удалён |
| `data.createdAt` | string | Дата и время создания (ISO 8601) |
| `data.updatedAt` | string | Дата и время последнего изменения (ISO 8601) |
| `data.deletedAt` | string \| null | Дата и время удаления или `null`, если файл не удалён |
| `data.downloadUrl` | string | URL для скачивания файла |
| `data.detailUrl` | string | URL карточки файла в Битрикс24 |

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

При успешной загрузке возвращается HTTP-статус `201 Created`.

```json
{
  "success": true,
  "data": {
    "id": 9251,
    "name": "report.txt",
    "code": null,
    "storageId": 1,
    "type": "file",
    "folderId": 27,
    "deletedType": 0,
    "globalContentVersion": 1,
    "fileId": 34867,
    "size": 11,
    "createdBy": 1,
    "updatedBy": 1,
    "deletedBy": null,
    "createdAt": "2026-05-06T09:32:39.000Z",
    "updatedAt": "2026-05-06T09:32:39.000Z",
    "deletedAt": null,
    "downloadUrl": "https://example.bitrix24.ru/disk/downloadFile/...",
    "detailUrl": "https://example.bitrix24.ru/company/personal/user/1/disk/file/report.txt"
  }
}
```

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

400 — не указаны `filename` и `content`:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "filename and content (base64) are required."
  }
}
```


## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `MISSING_PARAMS` | Не переданы `filename` и `content`, либо не указан ни `folderId`, ни `storageId` |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 401 | `TOKEN_MISSING` | Токены доступа к порталу Битрикс24 недоступны |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `disk` |
| 404 | `ENTITY_NOT_FOUND` | Папка или хранилище с указанным ID не найдены |
| 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку при загрузке файла |
| 429 | `RATE_LIMITED` | Превышен лимит запросов |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

**Содержимое передаётся в Base64.** Файл кодируется в Base64 и передаётся как строка в поле `content`. Передача файла через `multipart/form-data` не поддерживается.

**Максимальный размер.** Лимит тела запроса для этого маршрута — 70 МБ. С учётом того, что base64 увеличивает размер примерно на треть, это соответствует исходному файлу около 50 МБ — запись звонка, типовые вложения. Битрикс24 дополнительно применяет собственное ограничение на размер файла Диска: при его превышении возвращается `422 BITRIX_ERROR`. Файлы в сотни МБ загружать через этот эндпоинт не предназначено.

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

- [Файлы](/docs/entities/files)
- [Папки](/docs/entities/folders)
- [Хранилища](/docs/entities/storages)
- [Удалить файл](/docs/entities/files/delete)