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

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

Permanently delete selected blocks

POST /v1/pages/:pageId/blocks/bulk-purge

Deletes several blocks of one page with no way to restore them: they do not go to the page trash. If even one block is not on the page, none is deleted.

Parameters

Parameter Type Required Description
ParameterpageId (path) Typenumber Requiredyes DescriptionPage ID. List: GET /v1/pages
Parameterscope (query) Typestring Requiredno DescriptionSite type: KNOWLEDGE — knowledge base, GROUP — workgroup site, MAINPAGE — main page. Omit the parameter for pages of other sites

Request fields (body)

Field Type Required Description
FieldblockIds Typenumber[] Requiredyes DescriptionIDs of blocks in the draft of page pageId, 1 to 50 items. List: GET /v1/pages/:pageId/blocks. Repeated IDs are deleted once, but every array item counts toward the limit of 50
Fieldimages Typeobject[] Requiredno DescriptionImage bindings to blocks of this page that should be removed, up to 50 items
Fieldimages[].blockId Typenumber Requiredyes DescriptionID of the block on page pageId the image is bound to
Fieldimages[].fileId Typenumber Requiredyes DescriptionID of the image file. Returned in data.fileId on upload: POST /v1/pages/:pageId/blocks/:blockId/files

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/pages/2417/blocks/bulk-purge" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"blockIds": [29479, 29481]}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/pages/2417/blocks/bulk-purge" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"blockIds": [29479, 29481]}'

JavaScript — personal key

javascript 
const response = await fetch("https://vibecode.bitrix24.com/v1/pages/2417/blocks/bulk-purge", {
  method: "POST",
  headers: {"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({"blockIds": [29479, 29481]}),
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
console.log(result.data)

JavaScript — OAuth application

javascript 
const response = await fetch("https://vibecode.bitrix24.com/v1/pages/2417/blocks/bulk-purge", {
  method: "POST",
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({"blockIds": [29479, 29481]}),
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
console.log(result.data)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.pageId Typenumber DescriptionPage ID
Fielddata.deletedBlockIds Typenumber[] DescriptionIDs of the deleted blocks, without repeats. After the write, none of them is on the page, confirmed by a second read

Response example

JSON 
{
  "success": true,
  "data": {
    "pageId": 2417,
    "deletedBlockIds": [
      29479,
      29481
    ]
  }
}

Error response example

404 — a request {"blockIds": [29451, 29457]}, where block 29457 belongs to another page; no block is deleted:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Blocks not found on this page.",
    "blockIds": [
      29457
    ]
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionblockIds must be a non-empty array. — the body has no blockIds, it is not an array, or the array is empty
HTTP400 CodeBLOCK_PURGE_LIMIT DescriptionAt most 50 blocks and 50 images per request. — blockIds or images has more than 50 items. Repeated IDs count too
HTTP400 CodeINVALID_PARAMS DescriptionblockIds must contain positive safe integers. — blockIds contains a value that is not a positive integer
HTTP400 CodeINVALID_PARAMS Descriptionimages must be an array. — images is not an array
HTTP400 CodeINVALID_PARAMS DescriptionEach image needs positive blockId and fileId. — an images item has no blockId or fileId, their values are not positive integers, or the item has other fields
HTTP400 CodeINVALID_PARAMS DescriptionPath ids must be positive safe integers. — pageId is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionBody must be a JSON object. — the body is not a JSON object
HTTP400 CodeINVALID_PARAMS DescriptionUnsupported body field. — the body contains a field that is not in the Request fields (body) table
HTTP400 CodeFST_ERR_CTP_EMPTY_JSON_BODY DescriptionThe Content-Type: application/json header is sent with an empty body. Send a body with blockIds
HTTP400 CodeINVALID_SCOPE Descriptionscope must be KNOWLEDGE, GROUP or MAINPAGE, or omitted. — scope is not KNOWLEDGE, GROUP or MAINPAGE
HTTP404 CodeENTITY_NOT_FOUND DescriptionBlocks not found on this page. — the block is not in the draft of page pageId: it belongs to another page, is in the trash, was deleted, the ID comes from the published version, or page pageId does not exist. The same applies to a block from images[].blockId. The IDs of such blocks are listed in error.blockIds
HTTP404 CodeENTITY_NOT_FOUND DescriptionPage or block not found. — Bitrix24 did not find the page or block during the deletion
HTTP422 CodeBITRIX_NO_EFFECT DescriptionBitrix24 returned an invalid block descriptor; the action cannot be confirmed. — Bitrix24 returned a block descriptor that could not be parsed
HTTP422 CodeBITRIX_NO_EFFECT DescriptionBitrix24 did not acknowledge the action. — Bitrix24 did not confirm the deletion
HTTP422 CodeBITRIX_NO_EFFECT DescriptionSome blocks survived permanent deletion; do not blindly retry. — after the deletion, some blocks are still on the page. Their IDs are in error.blockIds
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the action. The error text comes from Bitrix24
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the landing scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only. The request is rejected before Bitrix24 is called
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe Bitrix24 user the key is issued for has no permission to edit the page
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key in X-Api-Key is not found or has been revoked
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP409 CodeLANDING_MODULE_NOT_ENABLED DescriptionThe Sites module is not available on the Bitrix24 account
HTTP409 CodePORTAL_ADDRESS_CHANGED DescriptionA self-hosted Bitrix24 moved to a new address, but the key's webhook was issued for the old one. Reissue the key's webhook
HTTP429 CodeRATE_LIMITED DescriptionThe Bitrix24 request limit is exceeded. Retry the request in 1-2 seconds
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 did not respond, returned a server error, or sent a response larger than 8 MiB
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time

Full list of common API errors — Errors.

Known specifics

  • Image unbinding is not confirmed. Bitrix24 does not report the result of unbinding images: the response is 200 even when the block has no file with that fileId.
  • Partial deletion. On 422 with an error.blockIds list, the other blocks from the request are already deleted. Retry the call only for error.blockIds.
  • Retry after a lost response. If the blocks are already deleted, repeating the same request returns 404, lists the deleted blocks in error.blockIds and leaves the other blocks untouched. Remove those IDs from blockIds and call again.
  • The call changes the page draft. Site visitors see the change after the page is published with POST /v1/pages/:id/publication. See Pages for details.

See also