For AI agents: markdown of this page — /docs-content-en/entities/storages/folders.md documentation index — /llms.txt

Create a folder at storage root

POST /v1/storages/:id/folders

Creates a folder at the storage root. Unlike POST /v1/folders, 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, for example with filter[entityType]=user. The type dictionary 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

Terminal 
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

Terminal 
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
Fieldsuccess Typeboolean DescriptionWhether the request succeeded
Fielddata Typeobject DescriptionThe created folder
Fielddata.id Typenumber DescriptionIdentifier of the created folder
Fielddata.name Typestring DescriptionFolder name — the name value from the request
Fielddata.parentId Typenumber DescriptionParent folder ID — the storage root folder, the rootFolderId field in the storage list
Fielddata.storageId Typenumber DescriptionStorage ID, equal to id in the path
Fielddata.code Typestring DescriptionSymbolic code. Not saved on creation, returned as null
Fielddata.type Typestring DescriptionObject type, "folder" for a folder
Fielddata.realObjectId Typenumber DescriptionInternal object ID
Fielddata.detailUrl Typestring DescriptionLink to the folder in the Bitrix24 interface. Access is limited by the employee's Bitrix24 permissions
Fielddata.deletedType Typenumber DescriptionDeletion status. A new folder has 0 — not deleted
Fielddata.createdBy Typenumber DescriptionCreator user ID. Lookup: GET /v1/users
Fielddata.updatedBy Typenumber DescriptionID of the user who made the last change. Lookup: GET /v1/users
Fielddata.deletedBy Typenumber DescriptionID of the user who deleted the folder. A new folder has null
Fielddata.createdAt Typedatetime DescriptionCreation date and time (ISO 8601 UTC)
Fielddata.updatedAt Typedatetime DescriptionDate and time of the last change
Fielddata.deletedAt Typedatetime DescriptionDeletion date and time. A new folder has null

HTTP 201, a folder in the folders 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
HTTP400 CodeINVALID_ID DescriptionInvalid storage ID
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionMissing name, empty or invalid name, unknown fields
HTTP400 CodeINVALID_PARAMS DescriptionMissing name, empty or invalid name, unknown fields
HTTP403 CodeSCOPE_DENIED DescriptionScope, key access mode or Bitrix24 permissions
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionScope, key access mode or Bitrix24 permissions
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionScope, key access mode or Bitrix24 permissions
HTTP404 CodeENTITY_NOT_FOUND DescriptionStorage not found
HTTP422 CodeBITRIX_ERROR DescriptionDuplicate name, Bitrix24 business refusal or no folder returned
HTTP422 CodeOPERATION_FAILED DescriptionDuplicate name, Bitrix24 business refusal or no folder returned

Common refusals: 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