블록 값

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

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

rich_text는 속성과 같은 조각을 사용합니다. 텍스트 조각 자세히 알아보기 → 읽은 값은 대체로 그대로 다시 보낼 수 있습니다. 예외는 다음과 같습니다.

읽은 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로 페이지 만들기를 사용하세요. 인라인 데이터베이스는 API로 만들 수 없습니다. 파일 업로드는 제공하지 않으므로 file_upload 값은 404를 반환합니다.

중첩 단계

요청 하나에는 최상위를 포함해 블록을 3단계까지 담을 수 있습니다. column_list와 그 column 블록은 한 단계로 셉니다. 더 깊이 넣으려면 다음 요청에서 3단계 블록에 추가하세요. column_list는 요청의 최상위에만 둘 수 있고, table은 3단계에 둘 수 없습니다. 더 깊이 넣으려면 다음 요청에서 그 블록에 추가하세요. 항목 수와 크기 상한은 값과 요청 크기에서 확인할 수 있습니다.

색

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:` 뒤에 여러 줄	값의 형식은 맞지만 의미가 틀렸습니다. 예를 들어 주소가 틀렸거나 사람을 찾을 수 없습니다. 문제를 모두 보여 줍니다.

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

공통

사용자

검색

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

페이지

블록

비동기 작업

댓글

블록 종류

중첩 단계

색

아이콘

링크와 파일

저장할 때 바뀌는 값

언어 값

표

열

탭

동기화 블록

오류

​블록 종류

​중첩 단계

​색

​아이콘

​링크와 파일

​저장할 때 바뀌는 값

​언어 값

​표

​열

​탭

​동기화 블록

​오류

블록 종류

중첩 단계

색

아이콘

링크와 파일

저장할 때 바뀌는 값

언어 값

표

열

탭

동기화 블록

오류