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

Move a block

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

Moves the block to the required toPageId, retaining its ID. Move between pages, including sites of the same type. Use up/down for order within a page.

Requires landing scope. A READONLY key receives 403 before calling Bitrix24. Changes affect the draft.

Request parameters

Field Type Required Description
pageId integer yes Source page from List pages.
blockId integer yes Block on the source page. Obtain its ID from copy/move.
scope string no Query: KNOWLEDGE, GROUP, MAINPAGE; omit for ordinary sites.
toPageId integer yes Destination page; copy defaults to the source.
afterBlockId integer no Block on destination page; foreign or missing anchor returns 400 before writing.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/pages/42/blocks/31/move" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"toPageId": 43}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/pages/42/blocks/31/move" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"toPageId": 43}'

JavaScript — personal key

javascript 
const response = await fetch("https://vibecode.bitrix24.com/v1/pages/42/blocks/31/move", {
  method: "POST",
  headers: { "X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({"toPageId": 43})
});
const result = await response.json();

JavaScript — OAuth application

javascript 
const response = await fetch("https://vibecode.bitrix24.com/v1/pages/42/blocks/31/move", {
  method: "POST",
  headers: { "X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({"toPageId": 43})
});
const result = await response.json();

Response fields

Field Type Description
success boolean Successful response.
data object Operation result.
data.blockId integer Block ID after the action.
data.pageId integer Result page ID.

Response

JSON 
{
  "success": true,
  "data": {
    "blockId": 31,
    "pageId": 43
  }
}

Errors

HTTP Code Reason
400 INVALID_PARAMS Invalid ID, body or destination anchor.
400 MISSING_REQUIRED_FIELDS Missing required field.
403 SCOPE_DENIED / WRITE_BLOCKED_READONLY_KEY Missing landing or read-only key.
409 LANDING_MODULE_NOT_ENABLED The Sites module is unavailable on the portal.
404 ENTITY_NOT_FOUND Missing page or block does not belong to source page.
422 BITRIX_ERROR / BITRIX_NO_EFFECT Bitrix24 refusal or unconfirmed result; do not blindly retry deletion.

Common errors.

Each Bitrix24 response is bounded to 8 MiB; exceeding the cap returns 502. Do not blindly retry an unconfirmed action: copy may create another block and up/down will change the order again.