## 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](/docs/entities/pages/list). |
| `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

```bash
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

```bash
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](/docs/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.