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

Move a block down

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

Moves one position down. The last block returns 409 BLOCK_WRONG_SORT.

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.

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

JavaScript — OAuth application

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

Response fields

Field Type Description
success boolean Successful response.
data object Operation result.
data.pageId integer Result page ID.
data.blockIds integer[] Block IDs in read-back page order.

Response

JSON 
{
  "success": true,
  "data": {
    "pageId": 42,
    "blockIds": [
      31,
      32
    ]
  }
}

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.
409 BLOCK_WRONG_SORT Order boundary.

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.