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

Create folder

POST /v1/folders

Creates a new folder inside the specified parent folder. The body is passed flat, without a fields wrapper.

Request fields (body)

Field Bitrix24 Type Required Description
name NAME string yes Name of the new folder
parentId PARENT_ID number yes ID of the parent folder. The storage root folder is rootFolderId from GET /v1/storages

The code field is read-only — it is not saved on creation, and passing it returns 400 READONLY_FIELD.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/folders" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Documents","parentId":27}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/folders" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Documents","parentId":27}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/folders', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Documents', parentId: 27 }),
})

const { success, data } = await res.json()
console.log('Folder created:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/folders', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Documents', parentId: 27 }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data object The created folder object. For all fields, see Folder fields

The folder card URL in Bitrix24 is built from id: https://<portal>.bitrix24.com/company/personal/user/1/disk/path/<name>/. <portal> is the portal domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 9301,
    "name": "Documents",
    "code": null,
    "storageId": 1,
    "type": "folder",
    "realObjectId": 9301,
    "parentId": 27,
    "deletedType": 0,
    "createdAt": "2026-06-25T12:10:00.000Z",
    "updatedAt": "2026-06-25T12:10:00.000Z",
    "deletedAt": null,
    "createdBy": 1,
    "updatedBy": 1,
    "deletedBy": null,
    "detailUrl": "https://<portal>.bitrix24.com/company/personal/user/1/disk/path/Uploaded files/Documents"
  }
}

Error response example

400 — the required name field is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Body field \"name\" is required to create diskFolder."
  }
}

Errors

HTTP Code Description
400 MISSING_REQUIRED_FIELDS The name field is missing
400 MISSING_PARENT_ID The parentId field is missing
400 READONLY_FIELD A read-only field was passed in the body, for example code
403 SCOPE_DENIED The API key does not have the disk scope
401 TOKEN_MISSING The API key has no configured portal tokens

For the full list of common API errors, see Errors.

See also