For AI agents: markdown of this page — /docs-content-en/entities/pages/blocks/restore.md documentation index — /llms.txt

Restore a block

POST /v1/pages/:pageId/blocks/:blockId/restore

Returns a block from the page trash to the page draft. You can restore a block that was moved to the trash by the block delete call.

Parameters

Parameter Type Required Description
pageId (path) number yes Page ID. List: GET /v1/pages
blockId (path) number yes ID of the block in the page trash. List: GET /v1/pages/:pageId/blocks?deleted=true. A ready-made call with this ID comes in the restoreWith field of the block delete response
scope (query) string no Site type: KNOWLEDGE — knowledge base, GROUP — workgroup site, MAINPAGE — main page. Omit the parameter for pages of other sites

No request body is needed.

Examples

curl — personal key

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

curl — OAuth application

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

if (body.success) {
  console.log('Block is back in the draft, publish with:', body.data.publishWith)
}

JavaScript — OAuth application

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

if (body.success) {
  console.log('Block is back in the draft, publish with:', body.data.publishWith)
}

Response fields

Field Type Description
success boolean true — the block was returned from the trash
data.id number ID of the restored block
data.deleted boolean Always false: the block is back in the page draft
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

Response example

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

Error response example

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

JSON 
{
  "success": false,
  "error": {
    "code": "BLOCK_NOT_IN_DRAFT",
    "message": "No such block in this page's trash. List it with GET /v1/pages/{pageId}/blocks?deleted=true."
  }
}

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 trash: the block is already restored, was never deleted, or does not exist. The error text differs from the delete response and refers to the trash
404 ENTITY_NOT_FOUND The page does not exist or is not visible to the key. A knowledge base, workgroup or main page requires the scope parameter
404 ENTITY_NOT_FOUND The trash check found the block, but during the restore Bitrix24 responded that the block is not on the page
502 BLOCK_LIST_UNCONFIRMED Bitrix24 did not return the page trash, so the block could not be checked before the restore. The block is untouched
502 BLOCK_RESTORE_UNCONFIRMED Bitrix24 did not confirm the restore. Check the draft block list before retrying
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 has no 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

  • Retry after a lost response. A repeated call for a block that has already left the trash returns 404 BLOCK_NOT_IN_DRAFT, not success. To find out whether the first call worked, look for the block in the draft block list.

See also