> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bottari.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 블록 수정하기

> 블록의 내용이나 설정을 바꾸거나 지운 블록을 되살립니다. 내용 수정 권한이 필요합니다.

블록 하나를 고치거나, 휴지통에 넣거나, 휴지통에서 되살립니다. `내용 수정` 권한이 필요합니다. 보낸 필드만 바뀌지만, 제목 블록과 목록 항목에는 항상 `rich_text`가 필요합니다. 빈 본문은 아무것도 바꾸지 않고 200을 반환합니다.

문서나 하위 문서의 제목을 바꾸려면 [페이지 수정하기](https://developers.bottari.ai/ko/api-reference/pages/update.md)를 사용하세요. 여기에 문서 ID를 보내면 400입니다.

**Authorization** `string` *required*

`Bearer <토큰>` 형식입니다. [토큰 자세히 알아보기 →](https://developers.bottari.ai/ko/auth/tokens.md)

**Bottari-Version** `string`

선택 항목입니다. `2026-03-11`만 받습니다. 빼면 현재 버전을 사용하고, 다른 값을 보내면 400을 반환합니다.

**id** `string` *required*

블록 ID입니다.

**\<block type>** `object`

키는 블록의 현재 종류이고, 값에는 바꿀 필드를 담습니다. 아래 표를 확인하세요.

**in\_trash** `boolean`

`true`면 [블록 지우기](https://developers.bottari.ai/ko/api-reference/blocks/delete.md)처럼 블록을 지우고, `false`면 되살립니다. 종류 키와 함께 보내면 둘 다 저장합니다.

## 바꿀 수 있는 필드

| 블록 | 필드 |
| - | - |
| `quote` · `toggle` | `rich_text` · `color` |
| `bulleted_list_item` · `numbered_list_item` | `rich_text`(필수) · `color` |
| `paragraph` | `rich_text` · `color`. `icon`은 탭의 문단만 받습니다. |
| 제목 블록 | `rich_text`(필수) · `color` · `is_toggleable` |
| `to_do` | `rich_text` · `color` · `checked` |
| `callout` | `rich_text` · `color` · `icon` |
| `code` | `rich_text` · `language` · `caption` |
| `equation` | `expression` |
| `bookmark` · `embed` | `url` |
| `image` | `external.url` · `caption` |
| 올린 `image` · `video` · `audio` · `pdf` · `file` | `caption`. 파일은 바꿀 수 없습니다. |
| `link_to_page` | `page_id` 또는 `database_id`. 대상을 읽을 수 있어야 합니다. |
| `table` | `has_column_header` · `has_row_header` |
| `table_row` | `cells` |
| `column` | `width_ratio` |

## 규칙

* 블록 종류는 바꿀 수 없습니다. 400 `Block type mismatch: ...`입니다.
* `table_of_contents.color`와 `bookmark` · `embed`의 `caption`은 받지만 무시합니다.
* `table_width`와 `synced_from`은 바꿀 수 없습니다. 현재 `synced_from`을 그대로 보내면 아무 일도 일어나지 않습니다.
* 최상위에 `children` 키를 보내면 400입니다. 자식을 추가하려면 [블록 자식 추가하기](https://developers.bottari.ai/ko/api-reference/blocks/append.md)를 사용하세요. 종류 키 안의 `children`은 무시합니다.
* 자식이 있는 제목 블록은 `is_toggleable`을 끌 수 없습니다. 400 `Cannot remove toggle from ... You must remove its children first.`입니다.
* 병합한 칸이 있는 표의 행은 고칠 수 없습니다. 400입니다.
* 칸에 쓰면 그 칸은 텍스트 문단 하나로 바뀌므로, 칸 안의 그림이나 다른 문단은 지워집니다. 읽은 값을 그대로 다시 보내면 유지됩니다.
* 멘션 알림을 보내지 않으려면 블록을 추가할 때 `notifications`를 사용하세요. 이 엔드포인트는 이 키를 받지 않으며 항상 알림을 보냅니다.

## 댓글

텍스트를 바꾸면 그 텍스트에 단 인라인 댓글의 표식이 사라집니다. 댓글은 문서로 옮겨지고 `original_content_deleted: true`가 됩니다. 블록 ID가 아니라 문서 ID로 읽으세요. 읽은 `rich_text`를 그대로 보내면 표식이 유지됩니다. [마크다운으로 본문 수정하기](https://developers.bottari.ai/ko/api-reference/pages/update-markdown.md)도 댓글을 단 텍스트가 바뀌지 않으면 표식을 유지합니다.

## 응답

고친 블록 객체입니다. [블록 읽기 자세히 알아보기 →](https://developers.bottari.ai/ko/api-reference/blocks/retrieve.md)

## 오류

| 상태 | `code` | 원인 |
| - | - | - |
| 400 | `validation_error` | 값이 틀렸거나, 종류가 맞지 않거나, 대상이 문서입니다. 지운 블록은 `Can't edit block that is archived. You must unarchive the block before editing.`을 반환합니다. 지운 블록 아래의 블록은 `Can't edit page on block with an archived ancestor. You must unarchive the ancestor before editing page.`를 반환합니다. |
| 403 | `restricted_resource` | `내용 수정`이 꺼져 있거나, 작업 에이전트가 붙은 데이터베이스입니다. |
| 404 | `object_not_found` | 없거나 연동이 읽을 수 없는 블록입니다. 멘션한 사람을 연동이 볼 수 없어도 404입니다. |

공통 오류는 [공통 규칙](https://developers.bottari.ai/ko/api-reference/overview.md#오류)에서 확인할 수 있습니다.

```bash curl theme={null}
curl https://api.bottari.ai/v1/blocks/exampleRow01.exampleBlk01 \
  -X PATCH \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "to_do": {
      "checked": true
    }
  }'
```

```json 200 theme={null}
{
  "object": "block",
  "id": "exampleRow01.exampleBlk01",
  "parent": {
    "type": "page_id",
    "page_id": "exampleRow01"
  },
  "created_time": "2026-01-15T02:30:00.000Z",
  "last_edited_time": "2026-01-15T03:10:00.000Z",
  "created_by": {
    "object": "user",
    "id": "22222222-2222-4222-8222-222222222222"
  },
  "last_edited_by": {
    "object": "user",
    "id": "22222222-2222-4222-8222-222222222222"
  },
  "has_children": false,
  "in_trash": false,
  "type": "to_do",
  "to_do": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "변경 기록 고치기",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "변경 기록 고치기",
        "href": null
      }
    ],
    "checked": true,
    "color": "default"
  },
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```

```json 400 theme={null}
{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "Block type mismatch: this block is a `paragraph`, but your request includes fields for a `heading_1` block. Changing a block's type is not supported.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.