블록 수정하기

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
    }
  }'

{
  "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"
}

{
  "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"
}

PATCH

blocks

{id}

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
    }
  }'

{
  "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"
}

{
  "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"
}

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

string

필수

Bearer <토큰> 형식입니다. 토큰 자세히 알아보기 →

string

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

string

필수

블록 ID입니다.

object

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

boolean

true면 블록 지우기처럼 블록을 지우고, 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입니다. 자식을 추가하려면 블록 자식 추가하기를 사용하세요. 종류 키 안의 children은 무시합니다.
자식이 있는 제목 블록은 is_toggleable을 끌 수 없습니다. 400 Cannot remove toggle from ... You must remove its children first.입니다.
병합한 칸이 있는 표의 행은 고칠 수 없습니다. 400입니다.
칸에 쓰면 그 칸은 텍스트 문단 하나로 바뀌므로, 칸 안의 그림이나 다른 문단은 지워집니다. 읽은 값을 그대로 다시 보내면 유지됩니다.
멘션 알림을 보내지 않으려면 블록을 추가할 때 notifications를 사용하세요. 이 엔드포인트는 이 키를 받지 않으며 항상 알림을 보냅니다.

텍스트를 바꾸면 그 텍스트에 단 인라인 댓글의 표식이 사라집니다. 댓글은 문서로 옮겨지고 original_content_deleted: true가 됩니다. 블록 ID가 아니라 문서 ID로 읽으세요. 읽은 rich_text를 그대로 보내면 표식이 유지됩니다. 마크다운으로 본문 수정하기도 댓글을 단 텍스트가 바뀌지 않으면 표식을 유지합니다.

응답

고친 블록 객체입니다. 블록 읽기 자세히 알아보기 →

오류

상태	`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입니다.

공통 오류는 공통 규칙에서 확인할 수 있습니다.

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
    }
  }'

{
  "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"
}

{
  "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"
}

공통

사용자

검색

데이터베이스와 데이터 소스

페이지

블록

비동기 작업

댓글

바꿀 수 있는 필드

규칙

댓글

응답

오류

​바꿀 수 있는 필드

​규칙

​댓글

​응답

​오류

바꿀 수 있는 필드

규칙

댓글

응답

오류