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

# 속성 값

> 속성 종류마다 읽을 때 받는 값과 쓸 때 보내는 값을 정리합니다.

`properties`의 키는 속성 이름입니다. 쓸 때는 속성 이름이나 속성 ID를 키로 사용할 수 있습니다.

## 텍스트 조각

`title`과 `rich_text`는 텍스트 조각의 배열입니다.

**읽을 때**

```json theme={null}
{
  "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
}
```

조각의 `type`은 `text` · `mention` · `equation`입니다. `mention.type`은 `user` · `page` · `database` · `date` · `custom_emoji`입니다. 연동이 읽지 못하는 문서와 데이터베이스 멘션의 `plain_text`는 `Untitled`이고, 이런 데이터베이스 멘션은 `page` 멘션으로 반환합니다. `사용자 정보`가 `없음`인 연동이 읽는 사람 멘션은 `@Anonymous`입니다. 봇 멘션은 이름을 유지합니다.

긴 텍스트는 2,000자 이하의 조각 여러 개로 반환합니다. `rich_text[0]`에는 앞부분만 있습니다. 텍스트 전체를 읽으려면 조각을 모두 합치세요.

**쓸 때**

```json theme={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조각까지입니다. [값과 요청 크기 자세히 알아보기 →](https://developers.bottari.ai/ko/limits/values.md#긴-텍스트)
* 같은 서식의 조각은 저장할 때 합칩니다. 읽으면 2,000자 단위로 나뉩니다.
* 읽은 텍스트 조각은 그대로 다시 쓸 수 있습니다. 사람 멘션은 `{ "id": "..." }`만 남겨 보내세요.
* 없는 문서 ID로 쓴 멘션은 200이고, 읽으면 `Untitled` 문서 멘션입니다. 없는 팀 이모지 ID의 조각은 버립니다.
* 빈 텍스트 조각은 저장하지 않습니다.
* 끝이 시작보다 앞선 날짜 멘션은 끝을 버립니다.

## 쓸 수 있는 속성

| 종류 | 쓰는 값 | 규칙 |
| - | - | - |
| `title` | 텍스트 조각 배열 | 빈 배열이면 빈 제목입니다. 줄바꿈은 공백으로 바뀌고 앞뒤 공백은 지워집니다. 하위 문서는 이 속성만 받습니다. |
| `rich_text` | 텍스트 조각 배열 | 빈 배열이면 값을 지웁니다. |
| `number` | 수 또는 `null` | 문자열은 400을 반환합니다. |
| `checkbox` | `true` 또는 `false` | 문자열은 400입니다. |
| `select` | `{ "id" }` · `{ "name" }` · `{ "name", "color" }` · `null` | [선택지](#선택지)를 확인하세요. |
| `multi_select` | 위 항목의 배열 | 100개까지입니다. |
| `status` | `{ "id" }` · `{ "name" }` · `null` | 있는 선택지만 받습니다. `null`이면 그 속성의 기본 선택지입니다. |
| `date` | `{ "start", "end", "time_zone" }` · `null` | [날짜](#날짜)를 확인하세요. |
| `people` | `[{ "id" }]` | 100개까지입니다. 그 팀의 멤버 · 게스트 · 연동 봇을 받습니다. |
| `relation` | `[{ "id" }]` | 100개까지입니다. [관계](#관계)를 확인하세요. |
| `files` | [파일](#파일)을 확인하세요. | 100개까지입니다. |
| `url` | 텍스트 또는 `null` | 2,000자까지입니다. 형식은 검사하지 않습니다. 빈 텍스트는 400이고, 지우려면 `null`을 보내세요. |
| `email` · `phone_number` | 텍스트 또는 `null` | 100자까지입니다. 형식은 검사하지 않습니다. 빈 텍스트는 400입니다. |

## 읽기만 가능한 속성

`formula` · `rollup` · `unique_id` · `created_time` · `created_by` · `last_edited_time` · `last_edited_by` · `button`은 쓸 수 없습니다. 쓰면 400을 반환합니다.

| 종류 | 읽는 값 |
| - | - |
| `formula` | `{ "type": "string", "string": "..." }` · `number` · `boolean` · `date`. 숫자는 소수 12자리에서 반올림합니다. 빈 텍스트 속성을 그대로 반환하는 수식은 `""`이고, 시각이 있는 날짜를 그대로 반환하는 수식은 UTC(`+00:00`)입니다. |
| `rollup` | `{ "type": "number", "number": 3, "function": "sum" }` · `date` · `array` · `unsupported` |
| `unique_id` | `{ "prefix": "TASK", "number": 12 }` |
| `created_time` · `last_edited_time` | 분 단위 UTC 시각 |
| `created_by` · `last_edited_by` | 사용자 객체 또는 `null` |
| `button` | `{}` |

세션 · 연결된 페이지 · PR 속성은 응답에 나오지 않습니다.

## 선택지

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

## 날짜

**읽을 때**는 `time_zone`이 항상 `null`입니다. 시각이 있는 값에는 오프셋이 붙습니다.

```json theme={null}
{ "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`입니다.
* 이미 들어 있는 사람은 다시 확인하지 않습니다. `사용자 정보`가 `없음`이면 사람의 ID는 이미 속성이나 멘션에 들어 있어도 404를 반환합니다. 연동 봇과 빈 배열은 받습니다.

## 관계

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

## 파일

**읽을 때**

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

**쓸 때**

| 형식 | 동작 |
| - | - |
| `{ "name": "안내", "external": { "url": "https://..." } }` | 외부 URL을 넣습니다. http(s)만 받습니다. 이름은 필수이고 100자까지입니다. |
| `{ "name": "...", "file": { "url": "<읽은 서명 주소>" } }` | 그 속성에 이미 있는 파일을 유지합니다. 만료된 주소도 됩니다. 맞는 파일이 없는 주소는 버리고, Bottari 서명 주소가 아니면 400입니다. |

## 자주 발생하는 검증 오류

| 메시지 | 원인 |
| - | - |
| `<키> is not a property that exists.` | 없는 속성이거나 숨겨진 종류입니다. |
| `<키> is expected to be <종류>.` | 속성과 값의 종류가 다릅니다. |
| `body failed validation. Fix one: ...` | 값의 형식이 틀렸습니다. 받을 수 있는 형식을 줄마다 보여 줍니다. |


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