속성 값

​

글 조각

{
  "type": "text",
  "text": {
    "content": "1월 주문을 확인했습니다.",
    "link": null
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "1월 주문을 확인했습니다.",
  "href": null
}

[
  {
    "text": {
      "content": "자세히 보기",
      "link": {
        "url": "https://example.com"
      }
    }
  },
  {
    "text": {
      "content": " 굵은 글"
    },
    "annotations": {
      "bold": true
    }
  },
  {
    "mention": {
      "user": {
        "id": "11111111-1111-4111-8111-111111111111"
      }
    }
  },
  {
    "mention": {
      "date": {
        "start": "2026-01-15"
      }
    }
  },
  {
    "equation": {
      "expression": "E = mc^2"
    }
  }
]

• 링크는 http(s) · mailto · 문서 상대 주소를 받습니다. 그 밖의 주소는 400 Invalid URL for link.입니다.
• 조각 하나는 2,000자, 배열은 100조각까지입니다. 값과 요청 크기 자세히 알아보기 →
• 같은 서식의 조각은 저장할 때 합칩니다. 읽으면 2,000자 단위로 나뉩니다.
• 읽은 글 조각은 그대로 다시 쓸 수 있습니다. 사람 멘션은 { "id": "..." }만 남겨 보내세요.
• 없는 문서 ID로 쓴 멘션은 200이고, 읽으면 Untitled 문서 멘션입니다. 없는 팀 이모지 ID의 조각은 버립니다.
• 빈 글 조각은 저장하지 않습니다.
• 끝이 시작보다 앞선 날짜 멘션은 끝을 버립니다.

​

쓸 수 있는 속성

​

읽기만 가능한 속성

​

선택지

• id와 name이 함께 오면 id를 사용합니다. 모르는 id는 400입니다.
• 이름은 앞뒤 공백을 자르고 대소문자를 구분하지 않고 맞춥니다.
• 맞는 이름이 없으면 select와 multi_select는 새 선택지를 만듭니다. 쓰기가 실패하면 새 선택지도 남지 않습니다.
• 이름에 쉼표가 있으면 400입니다.
• 색은 default · gray · brown · orange · yellow · green · blue · purple · pink · red 중 하나입니다. 있는 선택지에 다른 색을 보내면 400입니다.
• status는 새 선택지를 만들지 않습니다. 없는 이름은 400입니다.

​

날짜

{ "start": "2026-01-15T09:30:00.000+09:00", "end": null, "time_zone": null }

• 시작과 끝의 오프셋이 달라도 끝이 시작보다 앞서면 400입니다. 오프셋이 없는 시각과 날짜만 있는 값은 UTC로 읽어 비교합니다.
• time_zone을 보내려면 시작과 끝 모두 시각이어야 하고, 오프셋이 없거나 0이어야 합니다.
• 시각이 있는 값의 오프셋은 하나로 맞춥니다. 시작이 시각이면 시작의 오프셋(없으면 +00:00)을, 날짜만 있으면 끝의 오프셋을 사용합니다.
• 틀린 날짜는 400 ... date.start should be a valid ISO 8601 date string ...입니다.

​

사람

• 읽은 사용자 객체를 그대로 보내면 400입니다. { "id": "..." }로 보내세요.
• 모르는 ID와 그룹은 404 Could not find user with ID: ...입니다.
• 사람 수 제한이 있는 속성에 초과해 보내면 400 The request failed validation. Error: Invalid value for property with limit입니다.
• 이미 들어 있는 사람은 다시 확인하지 않습니다. 사용자 정보가 없음인 연동은 사람을 보낼 수 없습니다.

​

관계

• 쓰기는 값 전체를 바꿉니다. 읽기 응답의 relation은 25개까지이므로, has_more: true면 먼저 속성 값 읽기로 전부 읽으세요.
• 연동이 읽지 못하는 행의 ID는 404입니다.
• 대상 데이터베이스의 맨 위 행만 남습니다. 읽을 수 있는 다른 데이터베이스의 행과 하위 문서는 알리지 않고 버립니다.
• 연동이 볼 수 없는 기존 관계는 남습니다.
• 개수가 1개로 제한된 속성에 둘 이상 보내면 400 Relation property ... has a limit of 1, but ... values were provided.입니다.
• 작업 에이전트가 붙은 데이터베이스의 행을 넣거나 빼면 403입니다.

​

파일

[
  {
    "name": "계약서.pdf",
    "type": "file",
    "file": {
      "url": "https://...",
      "expiry_time": "2026-01-15T03:30:00.000Z"
    }
  },
  {
    "name": "안내",
    "type": "external",
    "external": {
      "url": "https://example.com/guide"
    }
  }
]

​

자주 발생하는 검증 오류