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

# 블록 자식 추가하기

> 문서나 블록 안에 블록을 추가합니다. 내용 추가 권한이 필요합니다.

문서나 블록 안에 블록을 추가합니다. `내용 추가` 권한이 필요합니다. 블록이 하나라도 거절되면 아무것도 저장하지 않습니다.

**Authorization** `string` *required*

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

**Bottari-Version** `string`

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

**id** `string` *required*

문서 ID나 블록 ID입니다.

**children** `object[]` *required*

블록 100개까지입니다. [블록 값 자세히 알아보기 →](https://developers.bottari.ai/ko/api-reference/block-values.md)

**position** `object`

추가할 위치입니다. 기본값은 끝입니다.

* `{ "type": "end" }`
* `{ "type": "start" }`
* `{ "type": "after_block", "after_block": { "id": "..." } }`

**notifications** `object`

`{ "mode": "silent" }`를 보내면 이 블록의 멘션 알림을 보내지 않습니다. 기본값은 `default`입니다.

## 위치

* `after_block`에는 대상의 바로 아래 자식만 넣을 수 있습니다. 다른 곳의 블록은 400이고, 없는 ID는 404입니다.
* `after_block`의 블록을 API로 지웠으면 새 블록은 끝에 들어갑니다. 그 부모를 지웠으면 400입니다.
* 문서가 편집기가 넣은 빈 줄로 끝나면 새 블록은 그 앞에 들어갑니다.

## 대상별로 받는 블록

`table_row`는 `table`에만, `column`은 `column_list`에만 넣을 수 있습니다. 다른 곳에 넣으면 400입니다.

| 대상 | 받는 블록 |
| - | - |
| 문서 · 하위 문서 | 모든 블록 종류를 받습니다. |
| `toggle` · 목록 항목 · `to_do` · `quote` · `callout` · `column` | 모든 블록 종류를 받습니다. |
| `paragraph` | 모든 블록 종류를 받습니다. 자식은 들여쓰기로 표시됩니다. |
| 제목 블록 | `is_toggleable`이 `true`면 모든 블록 종류를 받습니다. 아니면 400 `Block does not support children.`입니다. |
| `table` | `table_row`만 받습니다. 칸 수는 `table_width`와 같아야 합니다. |
| `column_list` | `column`만 받습니다. 열은 5개까지입니다. |
| `tab` | `paragraph`만 받습니다. 하나마다 새 탭이 됩니다. |
| 원본 `synced_block` | `synced_block`을 뺀 모든 블록 종류를 받습니다. |
| `synced_block` 사본 | 원본에 들어가고, 새 블록의 `parent`는 원본입니다. `after_block`은 400입니다. |

## 응답

블록 객체 목록입니다. 새 블록이 먼저 오고 그 뒤의 형제 블록이 따라오며, 100개까지 담습니다. 형제 블록이 더 있으면 `has_more`가 `true`입니다. 나머지는 [블록 자식 읽기](https://developers.bottari.ai/ko/api-reference/blocks/children.md)로 읽으세요.

`children: []`를 보내면 아무것도 추가하지 않고 대상의 현재 자식을 반환합니다.

## 오류

| 상태 | `code` | 원인 |
| - | - | - |
| 400 | `validation_error` | 블록 값이 틀렸거나, 상한을 넘었거나, 대상이 이 블록을 받을 수 없습니다. 휴지통에 있는 문서와, 지운 블록 및 그 자손도 이 오류를 반환합니다. |
| 400 | `validation_error` | 본문이 문서 상한을 넘습니다. `The page content is too large.`를 반환합니다. |
| 403 | `restricted_resource` | `내용 추가`가 꺼져 있거나, 작업 에이전트가 붙은 데이터베이스이거나, 팀의 블록 한도에 도달했습니다. |
| 404 | `object_not_found` | 대상이나 기준 블록이 없거나 연동이 읽을 수 없습니다. `file_upload` 값도 404입니다. |

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

```bash curl 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": [
      {
        "paragraph": {
          "rich_text": [
            { "text": { "content": "운영 팀에 검토를 요청하세요." } }
          ]
        }
      }
    ]
  }'
```

```json 200 theme={null}
{
  "object": "list",
  "results": [
    {
      "object": "block",
      "id": "exampleRow01.exampleBlk02",
      "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": "paragraph",
      "paragraph": {
        "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
          }
        ],
        "icon": null,
        "color": "default"
      }
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "block",
  "block": {},
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```

```json 400 theme={null}
{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "Block does not support children.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```


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