> ## 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 데스크톱 앱과 팀 소유자 권한이 필요합니다. 데이터베이스를 연결하려면 그 데이터베이스의 전체 허용 권한이 필요합니다.

**1. 연동 만들기**

데스크톱 앱에서 `설정` → `팀` → `API 연동` → `새 연동`을 누르고 `연동 이름`을 입력한 뒤 `만들기`를 누르세요.

> [!NOTE]
>
> 새 연동은 읽기만 할 수 있습니다. [권한 자세히 알아보기 →](https://developers.bottari.ai/ko/auth/capabilities.md)

**2. 토큰 복사하기**

연동 상세의 `비밀값`에서 `복사`를 누르고 토큰을 서버의 환경 변수에 넣으세요.

```bash theme={null}
export BOTTARI_TOKEN="bti_..."
```

> [!WARNING]
>
> 토큰을 소스 코드나 브라우저로 전달되는 파일에 넣지 마세요. 토큰이 있으면 연결된 데이터베이스를 읽을 수 있습니다.

**3. 데이터베이스 연결하기**

`연결된 데이터베이스`에서 `데이터베이스 추가`를 누르고 데이터베이스를 고른 뒤 `연결`을 누르세요.

> [!NOTE]
>
> 개인 데이터베이스는 연결할 수 없습니다. 스페이스 데이터베이스와 접근 제한 데이터베이스만 연결할 수 있습니다. [연결 범위 자세히 알아보기 →](https://developers.bottari.ai/ko/auth/connections.md)

**4. 연동 확인하기**

`GET /v1/users/me`로 토큰을 확인하세요.

```bash theme={null}
curl https://api.bottari.ai/v1/users/me \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11"
```

> [!NOTE]
>
> `Bottari-Version: 2026-03-11` 헤더는 선택 항목입니다. 빼면 현재 버전을 사용합니다. 이 엔드포인트는 권한과 상관없이 응답합니다.

**5. 데이터베이스 찾기**

검색으로 연결한 데이터베이스의 ID를 찾으세요.

```bash theme={null}
curl https://api.bottari.ai/v1/search \
  -X POST \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{ "filter": { "property": "object", "value": "data_source" } }'
```

> [!TIP]
>
> `query`를 빼면 연동이 볼 수 있는 데이터베이스를 모두 찾을 수 있어요.

**6. 행 읽기**

찾은 ID로 행을 읽으세요.

```bash theme={null}
curl https://api.bottari.ai/v1/data_sources/exampleDb001/query \
  -X POST \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{ "page_size": 10 }'
```

> [!NOTE]
>
> 정렬을 지정하지 않으면 최근에 만든 행부터 반환합니다.

**7. 행 쓰기(선택)**

`권한`에서 `내용 수정`을 켜고 행을 고치세요.

```bash theme={null}
curl https://api.bottari.ai/v1/pages/exampleRow01 \
  -X PATCH \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{ "properties": { "완료": { "checkbox": true } } }'
```

> [!NOTE]
>
> 쓰기 권한은 처음에 꺼져 있습니다. `내용 수정`을 켜면 행을 고칠 수 있고, `내용 추가`를 켜면 행을 만들 수 있습니다.

## 자주 발생하는 오류

| 응답 | 원인 | 해결 방법 |
| - | - | - |
| 401 `unauthorized` | 토큰이 없거나 틀렸습니다. | `Authorization: Bearer <토큰>` 헤더를 확인하세요. `새로 만들기`를 누르면 이전 토큰은 바로 거절됩니다. |
| 400 `validation_error`, `Bottari-Version ... is not supported` | 다른 버전을 보냈습니다. | `Bottari-Version: 2026-03-11`을 보내거나 헤더를 빼세요. |
| 403 `restricted_resource` | 필요한 권한이 꺼져 있습니다. | [권한](https://developers.bottari.ai/ko/auth/capabilities.md)을 확인하세요. |
| 404 `object_not_found` | ID가 없거나 연결하지 않은 데이터베이스입니다. | ID와 연결을 확인하세요. |

[전체 오류 코드 자세히 알아보기 →](https://developers.bottari.ai/ko/api-reference/overview.md#오류)


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