## Создать папку в корне хранилища

`POST /v1/storages/:id/folders`

Создаёт папку в корне хранилища. В отличие от [POST /v1/folders](/docs/entities/folders/create), искать `parentId` не нужно. Скоуп `disk`. READONLY-ключ получает 403.

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

`id` в пути — целое положительное ID хранилища. Найдите его через [GET /v1/storages](/docs/entities/storages/list), например с `filter[entityType]=user`. [Справочник типов](/docs/entities/storages/types) неполный.

Тело: `name` — обязательная непустая строка. Лишние поля, включая `rights`, не принимаются. Права наследуются от корня. Дубли имени Битрикс24 отклоняет, уникализации нет.

## Примеры

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

```bash
curl -X POST 'https://vibecode.bitrix24.tech/v1/storages/3/folders' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Reports"}'
```

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

```bash
curl -X POST 'https://vibecode.bitrix24.tech/v1/storages/3/folders' \
  -H 'X-Api-Key: YOUR_APP_KEY' \
  -H 'Authorization: Bearer USER_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Reports"}'
```

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

```javascript
const response = await fetch('https://vibecode.bitrix24.tech/v1/storages/3/folders', {
  method: 'POST',
  headers: {"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({"name": "Reports"}),
})
const result = await response.json()
console.log(result)
```

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

```javascript
const response = await fetch('https://vibecode.bitrix24.tech/v1/storages/3/folders', {
  method: 'POST',
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({"name": "Reports"}),
})
const result = await response.json()
console.log(result)
```

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

| Поле | Тип | Описание |
|---|---|---|
| `success` | boolean | Признак успешного запроса |
| `data` | object | Созданная [папка](/docs/entities/folders/get) |

HTTP 201, папка в проекции [folders](/docs/entities/folders/get).

```json
{"success":true,"data":{"id":7,"type":"folder","name":"Reports","parentId":9,"storageId":3}}
```

Запись не повторяется автоматически при сбое сети или таймауте. Исход может быть неизвестен: перечитайте содержимое корня перед повтором.

## Ошибки

Пример отказа (400):

```json
{"success":false,"error":{"code":"INVALID_ID","message":"id must be a positive integer."}}
```


| HTTP | Код | Описание |
|---|---|---|
| 400 | `INVALID_ID` | Неверный ID хранилища |
| 400 | `MISSING_REQUIRED_FIELDS` | Нет name, пустое или неверное имя, лишние поля |
| 400 | `INVALID_PARAMS` | Нет name, пустое или неверное имя, лишние поля |
| 403 | `SCOPE_DENIED` | Скоуп, режим ключа или права Битрикс24 |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Скоуп, режим ключа или права Битрикс24 |
| 403 | `BITRIX_ACCESS_DENIED` | Скоуп, режим ключа или права Битрикс24 |
| 404 | `ENTITY_NOT_FOUND` | Хранилище не найдено |
| 422 | `BITRIX_ERROR` | Дубль имени, бизнес-отказ Битрикс24 или ответ без папки |
| 422 | `OPERATION_FAILED` | Дубль имени, бизнес-отказ Битрикс24 или ответ без папки |

Общие отказы — [Ошибки](/docs/errors).

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

- [list](/docs/entities/storages/list)
- [create](/docs/entities/folders/create)
- [types](/docs/entities/storages/types)