لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/folders/purge.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Permanently delete folder

POST /v1/folders/:id/purge

Irreversibly deletes a folder and all its contents, bypassing the Bitrix24 trash. The method accepts both a folder in storage and a folder that is already in the trash. To be able to bring the folder back, move it to the trash instead.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionFolder ID. List: GET /v1/folders?parentId=X. Folders in the trash do not appear in the list — save the id before moving the folder to the trash. The storage root folder cannot be deleted

No request body.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/folders/10741/purge" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/folders/10741/purge" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/folders/10741/purge', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log('Folder permanently deleted:', body.data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/folders/10741/purge', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log('Folder permanently deleted:', body.data.id)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue — the folder is permanently deleted
Fielddata.id Typenumber DescriptionID of the deleted folder
Fielddata.purged Typeboolean DescriptionAlways true

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 10741,
    "purged": true
  }
}

Error response example

400 — the folder is the storage root:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "The storage root folder cannot be permanently deleted."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ID Descriptionid is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe folder is the storage root. The request is rejected before it reaches Bitrix24
HTTP401 CodeTOKEN_MISSING DescriptionThe key's portal has no authorization tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the disk scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode, and deletion changes portal data
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key owner has no permissions for the folder in Bitrix24
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo folder with this id, including on a repeated permanent deletion
HTTP422 CodeDISK_DELETE_REFUSED DescriptionBitrix24 refused the deletion. Tree deletion is not atomic: part of the contents may already be deleted — re-read the folder via GET /v1/folders/:id
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused the deletion; the reason is in message
HTTP429 CodeRATE_LIMITED DescriptionRequest rate limit exceeded — wait 1-2 seconds and retry
HTTP502 CodeDISK_OUTCOME_UNKNOWN DescriptionThe connection to Bitrix24 dropped after the delete request was sent. The outcome is unknown and the request was not retried. Re-read the folder: a 404 response means the folder is deleted
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 was unavailable while the folder was being read; the delete request was not sent

Full list of common API errors — Errors.

Known specifics

The whole tree is deleted. All nested folders and files are irreversibly deleted together with the folder, including those in the trash.

Permissions are checked only on the folder itself. Nested folders and files are deleted without a separate permission check on each of them.

Batch calls. Permanent deletion is not available in POST /v1/batch — call it as a separate request.

See also