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

# 블록 값

> 쓸 수 있는 블록 종류와 종류별 필드, Bottari가 저장하는 방식을 정리합니다.

블록은 블록 종류를 키로 한 객체 하나로 보냅니다. `type`은 선택 항목이고, 보내면 그 키와 같아야 합니다. `object: "block"`도 받습니다. 읽은 블록의 다른 키(`id` · `parent` 등)는 400을 반환하므로, 종류 키와 그 값만 보내세요.

```json theme={null}
{
  "paragraph": {
    "rich_text": [{ "text": { "content": "안녕하세요" } }],
    "color": "blue_background",
    "children": [
      { "to_do": { "rich_text": [{ "text": { "content": "안쪽 할 일" } }], "checked": false } }
    ]
  }
}
```

`rich_text`는 속성과 같은 조각을 사용합니다. [텍스트 조각 자세히 알아보기 →](https://developers.bottari.ai/ko/api-reference/property-values.md#텍스트-조각)

읽은 값은 대체로 그대로 다시 보낼 수 있습니다. 예외는 다음과 같습니다.

* 읽은 `paragraph`에는 `icon: null`이 있고, 이 값은 400을 반환합니다. `icon`을 빼고 보내세요.
* 읽은 `table` · `column_list` · `tab`에는 필수 필드인 `children`이 없습니다. 자식을 읽어 넣으세요.
* 읽은 `image`에는 `type`이 있고, 수정할 때 이 값은 400을 반환합니다. `type`을 빼고 보내세요.

## 블록 종류

| `type` | 필드 | 필수 |
| - | - | - |
| `paragraph` | `rich_text` · `color` · `children` | `rich_text` |
| `heading_1` · `heading_2` · `heading_3` · `heading_4` | `rich_text` · `color` · `is_toggleable` · `children` | `rich_text` |
| `bulleted_list_item` · `numbered_list_item` · `quote` · `toggle` | `rich_text` · `color` · `children` | `rich_text` |
| `to_do` | `rich_text` · `color` · `checked` · `children` | `rich_text` |
| `callout` | `rich_text` · `color` · `icon` · `children` | `rich_text` |
| `code` | `rich_text` · `language` · `caption` | `rich_text` · `language` |
| `equation` | `expression` | `expression` |
| `divider` · `breadcrumb` | 없음. `{}`를 보내세요. | |
| `table_of_contents` | `color` | |
| `bookmark` · `embed` | `url` · `caption` | `url` |
| `image` · `video` · `audio` · `pdf` | `external.url` · `caption` | `external.url` |
| `file` | `external.url` · `name` · `caption` | `external.url` |
| `link_to_page` | `page_id` 또는 `database_id` | 둘 중 하나 |
| `table` | `table_width` · `has_column_header` · `has_row_header` · `children` | `table_width` · `children` |
| `table_row` | `cells`(`rich_text` 배열의 배열) | `cells` |
| `column_list` | `children`(`column` 블록 2\~5개) | `children` |
| `column` | `children` · `width_ratio` | `children` |
| `tab` | `children`(탭마다 `paragraph` 하나) | `children` |
| `synced_block` | `synced_from` · `children` | `synced_from` |

`child_page` · `child_database` · `unsupported`는 쓸 수 없습니다. 하위 문서를 추가하려면 `parent.page_id`로 [페이지 만들기](https://developers.bottari.ai/ko/api-reference/pages/create.md)를 사용하세요. 인라인 데이터베이스는 API로 만들 수 없습니다.

파일 업로드는 제공하지 않으므로 `file_upload` 값은 404를 반환합니다.

## 중첩 단계

요청 하나에는 최상위를 포함해 블록을 3단계까지 담을 수 있습니다. `column_list`와 그 `column` 블록은 한 단계로 셉니다. 더 깊이 넣으려면 다음 요청에서 3단계 블록에 추가하세요.

`column_list`는 요청의 최상위에만 둘 수 있고, `table`은 3단계에 둘 수 없습니다. 더 깊이 넣으려면 다음 요청에서 그 블록에 추가하세요.

항목 수와 크기 상한은 [값과 요청 크기](https://developers.bottari.ai/ko/limits/values.md#본문)에서 확인할 수 있습니다.

## 색

`color`는 `default` · `gray` · `brown` · `orange` · `yellow` · `green` · `blue` · `purple` · `pink` · `red`와, 여기에 `_background`를 붙인 값(예: `blue_background`)을 받습니다.

| 보내는 값 | 읽을 때 받는 값 |
| - | - |
| 배경색 | 블록의 `color`가 그 값입니다. |
| 글자색 | 블록의 `color`는 `default`이고, 텍스트 조각마다 `annotations.color`에 그 값이 들어갑니다. 나중에 `default`를 보내도 지워지지 않습니다. 지우려면 `annotations.color`로 텍스트를 다시 쓰세요. |
| `callout` 색 | `gray_background` · `green_background` · `purple_background` · `orange_background` · `red_background` 다섯 가지 중 하나입니다. 색을 보내지 않으면 `gray_background`입니다. |
| `table_of_contents.color` | 무시합니다. 읽으면 `gray`입니다. |

## 아이콘

`callout.icon`은 `emoji` · `custom_emoji`(이 팀의 이모지) · `icon`(이름과 색)을 받습니다. `null`과 `external`은 400입니다. 아이콘을 보내지 않으면 콜아웃은 💡를 사용합니다.

## 링크와 파일

| 블록 | 규칙 |
| - | - |
| `bookmark` · `embed` | `url`은 http(s)여야 합니다. `caption`은 블록을 읽을 때 반환하지 않습니다. |
| `image` | `external.url`은 http(s)여야 합니다. 루프백과 사설 IP 주소는 400입니다. |
| `video` | 읽으면 `embed`입니다. `caption`은 반환하지 않습니다. |
| `audio` · `file` · `pdf` | 읽으면 `bookmark`입니다. `caption`과 `name`은 반환하지 않습니다. |
| `rich_text`의 링크 | 스킴이 없는 주소에는 `https://`를 붙입니다. `http` · `https` · `mailto` · `tel`을 받습니다. 문서 주소가 아닌 상대 주소는 400 `Invalid URL for link.`입니다. |

## 저장할 때 바뀌는 값

| 보내는 값 | 저장되는 값 |
| - | - |
| 서식이 같은 인접한 텍스트 조각 | 조각 하나로 합칩니다. 빈 조각은 지웁니다. |
| 문자열 안의 NUL 문자와 짝이 없는 서로게이트 | 지웁니다. |
| `code` 텍스트 · 멘션 · 날짜 · 수식의 서식 | 일반 텍스트와 값만 저장합니다. 서식은 저장하지 않습니다. |
| 시각이나 끝 날짜가 있는 날짜 멘션 | 시작 날짜만 저장합니다. |
| 페이지 멘션이나 한 페이지로 가는 링크만 있는 문단 | 같은 텍스트 끝에 공백을 붙입니다. 페이지 카드로 바뀌지 않고 텍스트로 남습니다. |
| `database_id`가 있는 `link_to_page` | 데이터베이스 멘션이 든 `paragraph`로 저장합니다. |
| `language: "shell"`인 `code` | 읽으면 `bash`입니다. |
| `width_ratio` | 다른 열에 대한 비율로 저장하므로 읽은 값이 다를 수 있습니다. 1보다 작아야 합니다. |
| `children`이 있는 제목 블록 | `is_toggleable: true`인 토글 제목으로 저장합니다. |

## 언어 값

`language`는 다음 값 중 하나여야 합니다.

`abap` · `abc` · `agda` · `arduino` · `ascii art` · `assembly` · `bash` · `basic` · `bnf` · `c` · `c#` · `c++` · `clojure` · `coffeescript` · `coq` · `css` · `dart` · `dhall` · `diff` · `docker` · `ebnf` · `elixir` · `elm` · `erlang` · `f#` · `flow` · `fortran` · `gherkin` · `glsl` · `go` · `graphql` · `groovy` · `haskell` · `hcl` · `html` · `idris` · `java` · `javascript` · `json` · `julia` · `kotlin` · `latex` · `less` · `lisp` · `livescript` · `llvm ir` · `lua` · `makefile` · `markdown` · `markup` · `matlab` · `mathematica` · `mermaid` · `nix` · `objective-c` · `ocaml` · `pascal` · `perl` · `php` · `plain text` · `powershell` · `prolog` · `protobuf` · `purescript` · `python` · `r` · `racket` · `reason` · `ruby` · `rust` · `sass` · `scala` · `scheme` · `scss` · `shell` · `smalltalk` · `solidity` · `sql` · `swift` · `toml` · `typescript` · `vb.net` · `verilog` · `vhdl` · `visual basic` · `webassembly` · `xml` · `yaml` · `java/c/c++/c#`

## 표

`table_width`는 표의 행마다 들어가는 칸 수이고, 모든 행의 칸 수가 이 값과 같아야 합니다. 나중에 바꿀 수 없습니다. 행을 추가하려면 표에 `table_row` 블록을 추가하세요.

## 열

`column_list`에는 열이 2개 이상 있어야 하고, 5개까지 담을 수 있습니다. 열을 지워 하나만 남으면 `column_list`가 사라지고 그 안의 블록은 `column_list`가 있던 자리로 옮겨집니다.

## 탭

`tab` 아래의 `paragraph` 하나가 탭 하나입니다. 문단의 텍스트는 탭 이름, `icon`은 탭 아이콘, `children`은 탭 내용입니다. `icon`은 이 문단에만 넣을 수 있습니다. 다른 곳에서는 400 `Cannot set icon on a paragraph block that is not a direct child of a tab block.`을 반환합니다.

## 동기화 블록

| `synced_from` | 결과 |
| - | - |
| `null` | 새 원본을 만듭니다. `children`이 원본의 내용이 됩니다. |
| `{ "block_id": "<원본 ID>" }` | 그 원본의 사본을 만들어 같은 내용을 보여 줍니다. `children`은 무시합니다. |

사본 ID에 추가한 블록은 원본에 들어갑니다. 원본 안에는 다른 동기화 블록을 넣을 수 없으며, 넣으면 400을 반환합니다. 사본을 만들려면 연동이 원본을 읽을 수 있어야 합니다.

## 오류

검증 메시지는 세 가지 형식입니다.

| 메시지 | 의미 |
| - | - |
| ``body failed validation: body.children[0].paragraph.rich_text should be defined, instead was `undefined`.`` | 이 경로의 값 하나가 틀렸습니다. |
| `body failed validation. Fix one:` 뒤에 여러 줄 | 블록이 어떤 종류와도 맞지 않습니다. 줄마다 한 종류의 첫 문제를 보여 줍니다. |
| `Content creation Failed. Fix the following:` 뒤에 여러 줄 | 값의 형식은 맞지만 의미가 틀렸습니다. 예를 들어 주소가 틀렸거나 사람을 찾을 수 없습니다. 문제를 모두 보여 줍니다. |

블록이 하나라도 거절되면 요청의 내용을 하나도 저장하지 않습니다.


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