For AI agents: markdown of this page — /docs-content-en/entities/pages/blocks/delete.md documentation index — /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
pageId (path) number yes Page ID. List: GET /v1/pages
blockId (path) number yes Block 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
scope (query) string no Site 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
success boolean true — the block was moved to the trash
data.id number ID of the deleted block
data.deleted boolean Always true: the block is in the page's trash
data.version string Page version the call changed. Always draft — the draft
data.published boolean Always false: the published version of the page did not change
data.publishWith string Call that publishes the page draft, with the page ID filled in
data.restoreWith string Call 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
400 INVALID_PAGE_ID pageId is not a positive integer
400 INVALID_BLOCK_ID blockId is not a positive integer
400 INVALID_SCOPE scope is not one of KNOWLEDGE, GROUP, MAINPAGE
400 INVALID_PARAMS Bitrix24 rejected the request: a required parameter is missing
404 BLOCK_NOT_IN_DRAFT No 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
404 ENTITY_NOT_FOUND The page does not exist or is not visible to the key. A knowledge base page, workgroup page or main page requires the scope parameter
404 ENTITY_NOT_FOUND The draft check found the block, but when moving it to the trash Bitrix24 responded that the block is not on the page
502 BLOCK_LIST_UNCONFIRMED Bitrix24 did not return the page draft, so the block could not be checked before deletion. The block is untouched
502 BLOCK_DELETE_UNCONFIRMED Bitrix24 did not confirm the move to the trash. Before retrying, check the trash with a ?deleted=true request
403 BITRIX_ACCESS_DENIED The employee the key was issued for has no permissions on the page in Bitrix24
422 BITRIX_ERROR Bitrix24 rejected the request. The error text is in message
403 SCOPE_DENIED The key lacks the landing scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only
401 TOKEN_MISSING The 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