## Replace block markup

`PATCH /v1/pages/:pageId/blocks/:blockId`

Replaces the entire HTML markup of a block on a landing page: the new markup is not merged with the current one.

Fields are passed flat at the root of the JSON, without a `fields` wrapper. Working with pages and their blocks is covered in [Pages](/docs/entities/pages).

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `pageId` (path) | number | yes | Page ID. List: [`GET /v1/pages`](/docs/entities/pages/list) |
| `blockId` (path) | number | yes | Block ID in the page draft. List: [`GET /v1/pages/:pageId/blocks`](/docs/entities/pages/blocks/list), which reads the draft by default. IDs from `?version=published` and IDs of blocks in the trash are not accepted |
| `scope` (query) | string | no | Bitrix24 section the page belongs to: `KNOWLEDGE` for the knowledge base, `GROUP` for a workgroup knowledge base, `MAINPAGE` for the main page. Omit it for a regular site page |

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `content` | string | yes | New HTML markup of the block. Fully replaces the current markup |
| `designed` | boolean | no | Flag for a block with its own design. Defaults to `false`. Also accepts the strings `"true"`, `"false"`, `"1"`, `"0"` and the numbers `1`, `0`. A block that does not support this flag responds with `422 BLOCK_DESIGN_NOT_SUPPORTED` |

## Examples

### curl — personal key

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/pages/20/blocks/32" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<section class=\"landing-block\"><div class=\"container\"><h2>Updated</h2><p>Second line</p></div></section>"
  }'
```

### curl — OAuth application

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/pages/20/blocks/32" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<section class=\"landing-block\"><div class=\"container\"><h2>Updated</h2><p>Second line</p></div></section>"
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/20/blocks/32', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: '<section class="landing-block"><div class="container"><h2>Updated</h2><p>Second line</p></div></section>',
  }),
})

const { success, data } = await res.json()
console.log('Publish with:', data.publishWith)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/20/blocks/32', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: '<section class="landing-block"><div class="container"><h2>Updated</h2><p>Second line</p></div></section>',
  }),
})

const { success, data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | The updated block and how to publish it |
| `data.id` | number | ID of the updated block, the same as in the path |
| `data.version` | string | Page version in which the block was changed. Always `draft` |
| `data.published` | boolean | Whether the change is published. Always `false` |
| `data.publishWith` | string | The call that publishes the page together with the change, with the page ID filled in. To publish only this block, see [Publish a block](/docs/entities/pages/block-publication) |

## Response example

```json
{
  "success": true,
  "data": {
    "id": 32,
    "version": "draft",
    "published": false,
    "publishWith": "POST /v1/pages/20/publication"
  }
}
```

## Error response example

404 — no block with this ID in the page draft:

```json
{
  "success": false,
  "error": {
    "code": "BLOCK_NOT_IN_DRAFT",
    "message": "No such block in this page's draft. Ids come from GET /v1/pages/{pageId}/blocks, which reads the draft by default; ids from the published version are not accepted here."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `MISSING_BLOCK_CONTENT` | `content` is missing or is not a string |
| 400 | `INVALID_DESIGNED` | `designed` is not a boolean value |
| 400 | `INVALID_PAGE_ID` | `pageId` in the path is not a positive integer |
| 400 | `INVALID_BLOCK_ID` | `blockId` in the path is not a positive integer |
| 400 | `INVALID_SCOPE` | `scope` is not `KNOWLEDGE`, `GROUP` or `MAINPAGE` |
| 400 | `INVALID_PARAMS` | Bitrix24 rejected the request: a required parameter is missing |
| 404 | `BLOCK_NOT_IN_DRAFT` | The block is not in the page draft: the ID does not exist, the block was moved to the trash, or the ID was taken from the published version |
| 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 draft check found the block, but when replacing the markup Bitrix24 responded that the block is not on the page |
| 422 | `BLOCK_DESIGN_NOT_SUPPORTED` | `designed: true` was passed, but the block does not support the `designed` flag. Retry the request without `designed` |
| 502 | `BLOCK_LIST_UNCONFIRMED` | Bitrix24 did not return the page draft: the block's presence was not checked and the markup was not changed |
| 502 | `BLOCK_CONTENT_UPDATE_UNCONFIRMED` | Bitrix24 did not confirm the markup replacement |
| 403 | `BITRIX_ACCESS_DENIED` | The employee the key was issued for has no access to the page in Bitrix24 |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request; the error text is in `message` |
| 403 | `SCOPE_DENIED` | The API key does not have the `landing` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

Full list of common API errors: [Errors](/docs/errors).

## Known specifics

**The block wrapper is preserved.** After the replacement, reading [`GET /v1/pages/:pageId/blocks?content=true`](/docs/entities/pages/blocks/list) returns the new markup inside the original `<div id="b<id>" class="block-wrapper …">` element.

## See also

- [List page blocks](/docs/entities/pages/blocks/list)
- [Add a block to a page](/docs/entities/pages/blocks/create)
- [Delete a block](/docs/entities/pages/blocks/delete)
- [Restore a block](/docs/entities/pages/blocks/restore)
- [Publish a block](/docs/entities/pages/block-publication)
- [Pages](/docs/entities/pages)