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

# 마크다운으로 본문 수정하기

> 문서 본문을 마크다운 텍스트로 추가하거나 바꾸거나 고칩니다. 내용 수정 권한이 필요합니다.

문서 본문을 텍스트로 고칩니다. `내용 수정` 권한이 필요합니다. `<page>` 태그로 하위 문서를 만들려면 `내용 추가` 권한도 필요합니다.

`type`에 수정 방식 하나를 지정하고, 같은 이름의 키에 그 방식의 객체를 보내세요.

**Authorization** `string` *required*

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

**Bottari-Version** `string`

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

**id** `string` *required*

문서 ID입니다. 블록 ID나 데이터베이스 ID는 400입니다.

**type** `string` *required*

`insert_content` · `update_content` · `replace_content_range` · `replace_content` 중 하나입니다.

**markdown\_version** `string` (default: v2)

`v2`만 받습니다. `v1`은 400입니다.

**allow\_async** `boolean`

`true`면 202와 작업을 반환합니다. [비동기 작업 읽기 자세히 알아보기 →](https://developers.bottari.ai/ko/api-reference/async-tasks/retrieve.md)

## 수정 방식

### insert\_content

문서에 내용을 추가합니다.

**insert\_content.content** `string` *required*

추가할 마크다운입니다.

**insert\_content.position** `object`

`{ "type": "start" }` 또는 `{ "type": "end" }`입니다. 기본값은 끝입니다.

**insert\_content.after** `string`

`position` 대신 이 텍스트 뒤의 새 줄에 추가합니다. 패턴은 `content_range`와 같습니다.

### update\_content

텍스트 일부를 바꿉니다. 바꾸지 않는 줄은 건드리지 않으므로, 사람이 입력 중일 수 있는 문서를 고칠 때 가장 안전합니다.

**update\_content.content\_updates** `object[]` *required*

순서대로 적용합니다. 항목마다 `old_str` · `new_str`과 선택 항목 `replace_all_matches`가 있습니다.

**update\_content.allow\_deleting\_content** `boolean`

`true`면 하위 문서와 인라인 데이터베이스를 지울 수 있습니다.

* `replace_all_matches`가 `true`가 아니면, `old_str`이 두 곳 이상과 일치할 때 400입니다.
* 일치하는 `old_str`이 하나도 없으면 400입니다. 일부만 일치하지 않으면 나머지를 적용하고, 응답의 `warnings`에 `no_match` 코드로 알립니다.

### replace\_content\_range

구간 하나를 바꿉니다.

**replace\_content\_range.content\_range** `string` *required*

`시작 텍스트...끝 텍스트` 또는 텍스트 하나입니다. 정확히 한 곳과 일치해야 합니다.

**replace\_content\_range.content** `string` *required*

새 마크다운입니다.

**replace\_content\_range.allow\_deleting\_content** `boolean`

`true`면 하위 문서와 인라인 데이터베이스를 지울 수 있습니다.

### replace\_content

본문 전체를 바꿉니다.

**replace\_content.new\_str** `string` *required*

새 마크다운입니다.

**replace\_content.allow\_deleting\_content** `boolean`

`true`면 하위 문서와 인라인 데이터베이스를 지울 수 있습니다.

> [!WARNING]
>
> `replace_content`는 버전을 검사하지 않습니다. 문서를 읽은 뒤 사람이 입력한 내용을 덮어씁니다. 사람이 편집 중일 수 있으면 `update_content`를 사용하세요.

## 텍스트를 찾는 방식

`old_str` · `after` · `content_range`는 앞서 보낸 텍스트가 아니라 [본문을 마크다운으로 읽기](https://developers.bottari.ai/ko/api-reference/pages/markdown.md)가 반환한 텍스트와 비교합니다. 굵은 글은 `<b>텍스트</b>`로 읽히므로 `**텍스트**`로는 일치하지 않습니다. 먼저 문서를 읽으세요.

올린 파일의 주소는 읽을 때마다 바뀝니다. 전체 주소 대신 `![](`로 찾으세요. `replace_content`는 파일 자체를 비교하므로 파일을 유지합니다.

## 저장 방식

새 텍스트를 현재 본문과 블록 단위로 비교합니다.

* 내용이 같은 블록은 그대로 두고 ID도 유지합니다.
* 바뀐 블록은 종류가 바뀌어도 ID를 유지합니다.
* 없어진 블록은 휴지통에 들어가고 되살릴 수 있습니다. [블록 지우기 자세히 알아보기 →](https://developers.bottari.ai/ko/api-reference/blocks/delete.md)
* 멘션은 항상 알림을 보냅니다. 여기서는 `notifications`를 받지 않습니다.

## 마크다운 형식

[본문을 마크다운으로 읽기](https://developers.bottari.ai/ko/api-reference/pages/markdown.md)가 반환하는 형식으로 보내세요. 문서를 읽어 같은 텍스트를 그대로 쓰면 아무것도 바뀌지 않습니다.

| 내용 | 마크다운 |
| - | - |
| 제목 | `#`\~`####` |
| 굵게 · 기울임 · 취소선 · 밑줄 · 코드 | `**텍스트**` 또는 `<b>` · `*텍스트*` 또는 `<i>` · `~~텍스트~~` 또는 `<s>` · `<u>` · `` `텍스트` `` |
| 링크 | `[텍스트](https://example.com)` |
| 수식 | `$E = mc^2$` 또는 `$$` 블록 |
| 글자색 | `<span color="green">텍스트</span>` |
| 배경색 | `<p color="blue_bg">텍스트</p>` |
| 빈 줄 | `<p />` |
| 문단 안의 블록 | `<p>`에 문단을 쓰고 그 뒤에 자식을 씁니다. |
| 목록 | `- 항목` · `1. 항목` · `- [ ] 할 일` · `- [x] 할 일` |
| 토글 | `<toggle>`. 첫 줄이 제목입니다. `<details>`도 받습니다. |
| 인용 | `> 텍스트` |
| 콜아웃 | `<callout icon="💡" color="gray_bg">텍스트</callout>` |
| 코드 | 언어를 지정한 펜스 코드 블록. 언어가 없거나 모르는 언어면 `javascript`로 저장하므로, 일반 텍스트에는 `txt`를 쓰세요. |
| 구분선 | `---` |
| 목차 | `<table-of-contents color="gray" />` |
| 그림 | `![alt](https://example.com/a.png)` |
| 북마크 · 임베드 | `<bookmark source="..." />` · `<embed source="..." />` |
| 표 | 파이프 표 또는 `<table>` |
| 열 | `<column ratio="50">`을 담은 `<columns>` |
| 탭 | `<tab>`을 담은 `<tabs>`. 첫 줄이 이름입니다. |
| 멘션 | `<mention url="..." />`(페이지) · `<mention url="user://<사람 ID>" />`(사람) · `<date start="2026-11-07" />`(날짜). 연동이 볼 수 없는 사람은 텍스트 `@Anonymous`가 되고 알림을 보내지 않습니다. |
| 하위 문서 | `<page url="...">제목</page>` |
| 인라인 데이터베이스 | `<database url="...">제목</database>` |
| 동기화 블록 | `<synced-block url="...">` · `<synced-block-reference url="...">` |
| 그 밖 | `<unknown url="..." alt="..." />` |

닫지 않은 태그는 400 `Markdown errors blocked parsing:`과 문제 목록을 반환합니다.

## 하위 문서와 데이터베이스 등 유지되는 블록

`<page url>` · `<database url>` · `<unknown>` · 동기화 블록 · 올린 파일은 이 문서에 이미 있는 블록을 가리킵니다. 읽어 온 문서에서만 동작합니다. 태그를 옮기면 블록도 옮겨집니다.

| 보내는 값 | 결과 |
| - | - |
| 현재 하위 문서나 인라인 데이터베이스가 빠진 텍스트 | `allow_deleting_content`가 `true`가 아니면 400 `This operation would delete ...`입니다. |
| `url` 없는 `<page>제목</page>` | 하위 문서를 만듭니다. 요청 하나에 100개까지입니다. |
| 이 문서의 자식이 아닌 페이지의 `<page url>` | 페이지 멘션이 됩니다. 연동이 읽을 수 없는 주소는 400입니다. |
| `url` 없는 `<database>제목</database>` | 400입니다. 데이터베이스는 만들 수 없습니다. |
| 내용이 빈 `<synced-block-reference>` | 그대로 유지합니다. |
| 텍스트를 바꾼 `<synced-block>` | 모든 사본의 내용이 바뀝니다. |

## 상한

| 대상 | 상한 |
| - | - |
| 요청 본문 | 500KB |
| 수정한 뒤의 텍스트 | 3MB |
| 요청 하나가 검사하는 텍스트 | 20MB. 500KB 문서라면 수정 약 40건에 해당합니다. |
| 요청 하나의 일치 수 | 200,000개 |
| 새 `<page>` 태그 · 새 동기화 블록 | 요청마다 100개 |
| 표 너비 | 100 |
| 마크다운을 읽는 시간 | 5초. 넘으면 400입니다. |

[블록 자식 추가하기의 블록 상한](https://developers.bottari.ai/ko/limits/values.md#본문)은 여기에 적용되지 않지만, 문서 상한은 적용됩니다. 긴 텍스트는 2,000자 단위의 조각으로 나뉩니다.

## 응답

[본문을 마크다운으로 읽기](https://developers.bottari.ai/ko/api-reference/pages/markdown.md)와 같은 `page_markdown` 객체입니다. 알릴 내용이 있으면 `warnings`가 추가됩니다.

## 오류

| 상태 | `code` | 원인 |
| - | - | - |
| 400 | `validation_error` | 요청 본문이나 마크다운이 틀렸거나, 텍스트를 찾지 못했거나 너무 많이 일치했거나, 휴지통에 있는 문서이거나, 상한을 넘었습니다. |
| 403 | `restricted_resource` | `내용 수정`이 꺼져 있거나, `<page>` 태그에 필요한 `내용 추가`가 꺼져 있거나, 작업 에이전트가 붙은 데이터베이스이거나, 연동이 쓸 수 없는 내용이 있거나, 팀의 블록 한도에 도달했습니다. |
| 404 | `object_not_found` | 없거나 연동이 읽을 수 없는 문서입니다. |

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

```bash curl 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": "디자인 팀에" }
      ]
    }
  }'
```

```json 200 theme={null}
{
  "object": "page_markdown",
  "id": "exampleRow01",
  "markdown": "## 출시 전\n\n디자인 팀에 검토를 요청하세요.\n\n- [x] 변경 기록 고치기",
  "truncated": false,
  "unknown_block_ids": [],
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```

```json 400 theme={null}
{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "No matches found for 운영 팀에.\n\nFetch the page again and base old_str on the current page text.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```


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