## Create a folder at storage root

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

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

## Request fields

The 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 non-empty string. Unknown fields, including `rights`, are rejected. Rights are inherited from the root. Bitrix24 rejects duplicate names; no automatic renaming occurs.

## Examples

### curl — personal key

```bash
curl -X POST 'https://vibecode.bitrix24.com/v1/storages/1379/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/1379/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/1379/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/1379/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 | Whether the request succeeded |
| `data` | object | The created folder |
| `data.id` | number | Identifier of the created folder |
| `data.name` | string | Folder name — the `name` value from the request |
| `data.parentId` | number | Parent folder ID — the storage root folder, the `rootFolderId` field in the [storage list](/docs/entities/storages/list) |
| `data.storageId` | number | Storage ID, equal to `id` in the path |
| `data.code` | string | Symbolic code. Not saved on creation, returned as `null` |
| `data.type` | string | Object type, `"folder"` for a folder |
| `data.realObjectId` | number | Internal object ID |
| `data.detailUrl` | string | Link to the folder in the Bitrix24 interface. Access is limited by the employee's Bitrix24 permissions |
| `data.deletedType` | number | Deletion status. A new folder has `0` — not deleted |
| `data.createdBy` | number | Creator user ID. Lookup: [`GET /v1/users`](/docs/entities/users/list) |
| `data.updatedBy` | number | ID of the user who made the last change. Lookup: [`GET /v1/users`](/docs/entities/users/list) |
| `data.deletedBy` | number | ID of the user who deleted the folder. A new folder has `null` |
| `data.createdAt` | datetime | Creation date and time (ISO 8601 UTC) |
| `data.updatedAt` | datetime | Date and time of the last change |
| `data.deletedAt` | datetime | Deletion date and time. A new folder has `null` |

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

## Response example

```json
{
  "success": true,
  "data": {
    "id": 10897,
    "name": "Reports",
    "code": null,
    "storageId": 1379,
    "type": "folder",
    "realObjectId": 10897,
    "parentId": 9057,
    "deletedType": 0,
    "createdAt": "2026-10-23T07:29:19.000Z",
    "updatedAt": "2026-10-23T07:29:19.000Z",
    "deletedAt": null,
    "createdBy": 1295,
    "updatedBy": 1295,
    "deletedBy": null,
    "detailUrl": "https://<portal>.bitrix24.com/company/personal/user/1295/disk/path/Reports"
  }
}
```

## Error response example

400 — invalid storage ID:

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

## Errors

| 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).

## Known specifics

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

## See also

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