## 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`](/docs/entities/pages/list) |
| `blockId` (path) | number | yes | ID of the block in the page trash. List: [`GET /v1/pages/:pageId/blocks?deleted=true`](/docs/entities/pages/blocks/list). A ready-made call with this ID comes in the `restoreWith` field of the [block delete](/docs/entities/pages/blocks/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

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

### curl — OAuth application

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

## See also

- [Delete a block](/docs/entities/pages/blocks/delete)
- [List page blocks](/docs/entities/pages/blocks/list)
- [Pages](/docs/entities/pages)
- [Errors](/docs/errors)