> ## 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.

# 본문 쓰기

> 블록 · 마크다운 · 템플릿 중 무엇을 쓸지 고르고, 사람이 편집 중일 때 쓰기가 어떻게 동작하는지 정리합니다.

문서 본문을 쓰는 방법은 세 가지입니다. 모두 같은 문서에 저장되며 섞어서 사용할 수 있습니다.

| 방법 | 알맞은 경우 | 엔드포인트 |
| - | - | - |
| 블록 | 특정 블록을 ID로 추가하거나 바꿀 때 | [추가](https://developers.bottari.ai/ko/api-reference/blocks/append.md) · [수정](https://developers.bottari.ai/ko/api-reference/blocks/update.md) · [지우기](https://developers.bottari.ai/ko/api-reference/blocks/delete.md) |
| 마크다운 | 문서를 텍스트로 쓰거나 고칠 때 | [페이지 만들기](https://developers.bottari.ai/ko/api-reference/pages/create.md) · [마크다운으로 본문 수정하기](https://developers.bottari.ai/ko/api-reference/pages/update-markdown.md) |
| 템플릿 | 팀이 앱에서 만든 구성으로 시작할 때 | [템플릿 목록 읽기](https://developers.bottari.ai/ko/api-reference/data-sources/templates.md) · [페이지 만들기](https://developers.bottari.ai/ko/api-reference/pages/create.md#템플릿) |

연동에는 작업마다 권한이 필요합니다. 추가하려면 `내용 추가`, 고치거나 지우려면 `내용 수정`이 필요합니다. 마크다운 수정에는 `내용 수정`만 있으면 됩니다. [권한 자세히 알아보기 →](https://developers.bottari.ai/ko/auth/capabilities.md)

## 문서 추가하기

행은 데이터베이스에, 하위 문서는 문서 아래에 들어갑니다.

```bash theme={null}
curl https://api.bottari.ai/v1/pages \
  -X POST \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": { "data_source_id": "exampleDb001" },
    "markdown": "# 출시 점검표\n\n- [ ] 변경 기록 고치기"
  }'
```

## 블록 추가하고 고치기

문서 끝에 블록을 추가하세요. 응답에 새 블록과 그 ID가 들어 있습니다.

```bash theme={null}
curl https://api.bottari.ai/v1/blocks/exampleRow01/children \
  -X PATCH \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      { "heading_2": { "rich_text": [{ "text": { "content": "결과" } }] } }
    ]
  }'
```

그런 다음 ID로 블록 하나를 고치세요. 보낸 필드만 바뀝니다.

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

## 텍스트로 고치기

문서를 읽은 뒤 텍스트 일부를 바꾸세요.

```bash theme={null}
curl https://api.bottari.ai/v1/pages/exampleRow01/markdown \
  -X PATCH \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "update_content",
    "update_content": {
      "content_updates": [
        { "old_str": "변경 기록 고치기", "new_str": "변경 기록 게시하기" }
      ]
    }
  }'
```

## 사람이 편집 중일 때

쓰기는 열려 있는 문서에 바로 들어가므로, 문서를 열어 둔 사람에게 바로 보입니다.

* 블록 쓰기는 그 블록의 줄만 건드립니다. 다른 곳에서 입력 중인 텍스트는 그대로 남습니다.
* `update_content`도 같습니다. 바꾸는 줄만 건드립니다.
* `replace_content`는 버전을 검사하지 않습니다. 문서를 읽은 뒤 입력한 내용을 덮어씁니다.
* 고치는 줄에서 누군가 입력 중일 때 문단에 첫 들여쓰기 자식을 추가하는 것처럼 그 줄을 담는 구조가 바뀌면, 커서가 다음 줄로 옮겨질 수 있습니다.

200을 받은 쓰기는 저장된 것입니다. 503은 저장을 확인하지 못했다는 뜻이고, 그 쓰기가 문서를 열어 둔 사람에게 이미 보일 수 있습니다. 블록 추가를 다시 보내기 전에 문서를 읽어, 블록이 두 번 들어가지 않게 하세요.

## 요청이 겹칠 때

이미 템플릿을 적용 중인 문서에 템플릿을 적용하면 409 `conflict_error`를 반환하고 아무것도 쓰지 않습니다. 요청을 다시 보내세요. 같은 문서에 동시에 보낸 다른 쓰기는 차례로 저장합니다.

## 지운 내용 되살리기

지운 블록은 30일 동안 휴지통에 남고, 되살릴 수 있습니다. 마크다운 편집과 `erase_content`로 없어진 블록도 같습니다. [블록 지우기 자세히 알아보기 →](https://developers.bottari.ai/ko/api-reference/blocks/delete.md)

## 멘션

새 내용에서 사람을 멘션하면 그 사람에게 알림을 보냅니다. 보내지 않으려면 [블록 자식 추가하기](https://developers.bottari.ai/ko/api-reference/blocks/append.md) · [페이지 만들기](https://developers.bottari.ai/ko/api-reference/pages/create.md) · [페이지 수정하기](https://developers.bottari.ai/ko/api-reference/pages/update.md)에서 `notifications: { "mode": "silent" }`를 보내세요. 블록 수정과 마크다운 편집은 항상 알림을 보냅니다.

알림에는 연동 이름이 나오지 않습니다. 누군가 멘션했다고만 표시됩니다.

## 웹훅

연동이 직접 쓴 변경도 `page.content_updated` 이벤트를 전송합니다. 반복을 막으려면 연동 봇만 쓴 이벤트를 건너뛰세요. [작성자 자세히 알아보기 →](https://developers.bottari.ai/ko/webhooks/events.md#작성자)


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