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

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

Delete a block

DELETE /v1/pages/:pageId/blocks/:blockId

Moves a page block to that page's trash. Deletion is reversible: while the block is in the trash, you can return it to the page with the restore method.

Parameters

Parameter Type Required Description
ParameterpageId (path) Typenumber Requiredyes DescriptionPage ID. List: GET /v1/pages
ParameterblockId (path) Typenumber Requiredyes DescriptionBlock ID from the page draft. List: GET /v1/pages/:pageId/blocks without the version parameter. Block IDs from the published version are not accepted here
Parameterscope (query) Typestring Requiredno DescriptionSite type: KNOWLEDGE — knowledge base, GROUP — workgroup site, MAINPAGE — main page. Omit the parameter for pages of other sites

Examples

curl — personal key

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/pages/20/blocks/30" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/pages/20/blocks/30" \
  -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/pages/20/blocks/30', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const body = await res.json()

if (body.success) {
  console.log('Block is in the trash, restore with:', body.data.restoreWith)
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/20/blocks/30', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const body = await res.json()

if (body.success) {
  console.log('Block is in the trash, restore with:', body.data.restoreWith)
}

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue — the block was moved to the trash
Fielddata.id Typenumber DescriptionID of the deleted block
Fielddata.deleted Typeboolean DescriptionAlways true: the block is in the page's trash
Fielddata.version Typestring DescriptionPage version the call changed. Always draft — the draft
Fielddata.published Typeboolean DescriptionAlways false: the published version of the page did not change
Fielddata.publishWith Typestring DescriptionCall that publishes the page draft, with the page ID filled in
Fielddata.restoreWith Typestring DescriptionCall that returns this block from the trash, with the page and block IDs filled in

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 30,
    "deleted": true,
    "version": "draft",
    "published": false,
    "publishWith": "POST /v1/pages/20/publication",
    "restoreWith": "POST /v1/pages/20/blocks/30/restore"
  }
}

Error response example

404 — the block is not in the page draft, for example, because it is already in the trash:

JSON 
{
  "success": false,
  "error": {
    "code": "BLOCK_NOT_IN_DRAFT",
    "message": "No such block in this page's draft. Ids come from GET /v1/pages/{pageId}/blocks, which reads the draft by default; ids from the published version are not accepted here."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PAGE_ID DescriptionpageId is not a positive integer
HTTP400 CodeINVALID_BLOCK_ID DescriptionblockId is not a positive integer
HTTP400 CodeINVALID_SCOPE Descriptionscope is not one of KNOWLEDGE, GROUP, MAINPAGE
HTTP400 CodeINVALID_PARAMS DescriptionBitrix24 rejected the request: a required parameter is missing
HTTP404 CodeBLOCK_NOT_IN_DRAFT DescriptionNo block with this ID in the page draft: the block is already in the trash, the ID comes from the published version, or it does not exist
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe page does not exist or is not visible to the key. A knowledge base page, workgroup page or main page requires the scope parameter
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe draft check found the block, but when moving it to the trash Bitrix24 responded that the block is not on the page
HTTP502 CodeBLOCK_LIST_UNCONFIRMED DescriptionBitrix24 did not return the page draft, so the block could not be checked before deletion. The block is untouched
HTTP502 CodeBLOCK_DELETE_UNCONFIRMED DescriptionBitrix24 did not confirm the move to the trash. Before retrying, check the trash with a ?deleted=true request
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe employee the key was issued for has no permissions on the page in Bitrix24
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. The error text is in message
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the landing scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens configured

Full list of common API errors — Errors.

Known specifics

  • A block in the trash drops out of the draft. You cannot replace its markup via PATCH /v1/pages/:pageId/blocks/:blockId until it is restored: the response is 404 BLOCK_NOT_IN_DRAFT. The block can be found in the list GET /v1/pages/:pageId/blocks?deleted=true.
  • Retry after a lost response. A repeated call for a block that is already in the trash returns 404 BLOCK_NOT_IN_DRAFT, not success. To find out whether the first call worked, look for the block in the list with ?deleted=true.
  • Irreversible deletion is a separate method. This call only moves the block to the trash. To delete a block with no way to restore it, see Permanently delete a block.

See also