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

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

Permanently delete file

POST /v1/files/:id/purge

Deletes a file irreversibly, bypassing the Bitrix24 trash: the method accepts both a file in a folder and a file that is already in the trash. To be able to bring the file back, move it to the trash instead.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionFile ID. List: GET /v1/files?folderId=X. Trashed files do not appear in the list — save the id before moving the file to the trash

No request body is sent.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/files/10751/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/files/10751/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('File permanently deleted:', body.data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/files/10751/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('File permanently deleted:', body.data.id)

Response fields

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

Response example

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

Error response example

404 — the file does not exist, including on a repeated permanent deletion:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Could not find entity with id '10751'."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ID Descriptionid is not a positive integer
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 on the file in Bitrix24
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo file with this id, including on a repeated permanent deletion
HTTP422 CodeDISK_DELETE_REFUSED DescriptionBitrix24 refused to delete the file: the file is locked or protected
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused to delete the file; the reason is in message
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded — wait 1-2 seconds and retry
HTTP502 CodeDISK_OUTCOME_UNKNOWN DescriptionThe connection to Bitrix24 dropped after the deletion was sent. The outcome is unknown and the request was not retried. Re-read the file via GET /v1/files/:id: a 404 response means the file is deleted
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 was unavailable while the file was being read; the deletion was not sent

Full list of common API errors — Errors.

Known specifics

What is deleted along with the file. All versions of the file, its public link, attachments of this file in tasks, chats, CRM fields and comments, and links to the file in other storages.

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

See also