## Create a folder at storage root

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

Creates a folder at storage root. Unlike [POST /v1/folders](/docs/entities/folders/create), no `parentId` lookup is needed. Requires `disk` scope. READONLY keys receive 403.

## Request fields

Path `id` is a positive integer storage ID. Find it through [GET /v1/storages](/docs/entities/storages/list), for example with `filter[entityType]=user`. The [type dictionary](/docs/entities/storages/types) is incomplete.

Body: `name` is a required nonempty string. Unknown fields, including `rights`, are refused. Rights are inherited from the root. Bitrix24 refuses duplicate names; no automatic renaming occurs.

## Examples

### curl — personal key

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

### curl — OAuth application

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

```javascript
const response = await fetch('https://vibecode.bitrix24.com/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 application

```javascript
const response = await fetch('https://vibecode.bitrix24.com/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)
```

## Response fields

| Field | Type | Description |
|---|---|---|
| `success` | boolean | Successful request |
| `data` | object | Created [folder](/docs/entities/folders/get) |

HTTP 201, a folder in the [folders](/docs/entities/folders/get) projection.

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

The write is not automatically replayed after network failure or timeout. Its outcome may be unknown: reread root contents before retrying.

## Errors

Example refusal (400):

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


| HTTP | Code | Description |
|---|---|---|
| 400 | `INVALID_ID` | Invalid storage ID |
| 400 | `MISSING_REQUIRED_FIELDS` | Missing name, empty or invalid name, unknown fields |
| 400 | `INVALID_PARAMS` | Missing name, empty or invalid name, unknown fields |
| 403 | `SCOPE_DENIED` | Scope, key access mode or Bitrix24 permissions |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Scope, key access mode or Bitrix24 permissions |
| 403 | `BITRIX_ACCESS_DENIED` | Scope, key access mode or Bitrix24 permissions |
| 404 | `ENTITY_NOT_FOUND` | Storage not found |
| 422 | `BITRIX_ERROR` | Duplicate name, Bitrix24 business refusal or no folder returned |
| 422 | `OPERATION_FAILED` | Duplicate name, Bitrix24 business refusal or no folder returned |

Common refusals: [Errors](/docs/errors).

## See also

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