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

# 공통 규칙

> 모든 엔드포인트에 적용되는 주소 · 헤더 · 응답 · 오류 · 목록 읽기 규칙을 정리합니다.

## 기본 주소

```text theme={null}
https://api.bottari.ai
```

엔드포인트는 모두 `/v1/`로 시작합니다. 없는 주소는 400 `invalid_request_url`을 반환합니다.

## 헤더

| 헤더 | 값 | 필수 여부 |
| - | - | - |
| `Authorization` | `Bearer <토큰>` | 필수 |
| `Bottari-Version` | `2026-03-11` | 선택. 빼면 현재 버전을 사용합니다. |
| `Content-Type` | `application/json` | 본문이 있는 요청 |

## 응답

모든 성공 응답의 최상위에는 `request_id`가 있습니다. 문의할 때 이 값을 알려 주세요. 이 문서의 응답 예제는 예시 값을 사용합니다.

## 오류

오류 응답의 형식은 다음과 같습니다. `additional_data`는 추가 정보가 있을 때만 포함됩니다.

```json theme={null}
{
  "object": "error",
  "status": 404,
  "code": "object_not_found",
  "message": "Could not find page with ID: exampleRow01. Make sure the relevant pages and databases are shared with your connection \"주문 동기화\".",
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```

| 상태 | `code` | 발생 조건 |
| - | - | - |
| 400 | `invalid_request_url` | 없는 경로이거나 메서드가 맞지 않습니다. 토큰을 확인하기 전에 거절합니다. |
| 400 | `invalid_json` | 본문이 JSON이 아닙니다. |
| 400 | `validation_error` | 버전이 `2026-03-11`이 아니거나 본문 또는 쿼리 값이 틀렸습니다. 요청 본문이 500KB를 넘어도 이 코드입니다. |
| 400 | `invalid_request` | 그 밖에 처리할 수 없는 요청입니다. |
| 401 | `unauthorized` | 토큰이 없거나 틀렸습니다. |
| 403 | `restricted_resource` | 권한이 꺼져 있거나 그 대상에 쓸 수 없습니다. |
| 404 | `object_not_found` | 없거나 연동이 볼 수 없는 대상입니다. |
| 429 | `rate_limited` | 호출 횟수를 넘겼습니다. [호출 횟수 제한 자세히 알아보기 →](https://developers.bottari.ai/ko/limits/rate-limits.md) |
| 500 | `internal_server_error` | 서버 오류입니다. |
| 503 | `service_unavailable` | 잠시 처리할 수 없습니다. 다시 보내세요. |

서버는 경로와 메서드 → JSON → 인증 → 버전 → 본문 값 순서로 검사합니다.

## 목록 읽기

목록 응답의 형식은 다음과 같습니다.

```json theme={null}
{
  "object": "list",
  "results": [],
  "next_cursor": null,
  "has_more": false,
  "type": "page_or_data_source",
  "page_or_data_source": {},
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```

* `page_size`는 1\~100이고 기본값은 100입니다.
* `has_more`가 `true`면 `next_cursor`를 다음 요청의 `start_cursor`로 보내세요.
* 커서는 그 쿼리에서만 사용할 수 있습니다. `POST /v1/data_sources/{id}/query`에서는 페이지마다 같은 `filter` · `sorts` · `in_trash` · `is_archived`를 키 순서까지 같게 보내세요. `start_cursor`와 `page_size`만 바꿀 수 있습니다. 다르면 커서가 400을 반환합니다.

## ID

| 대상 | 형식 |
| - | - |
| 데이터베이스 · 데이터 소스 · 행 · 하위 문서 · 속성 · 선택지 · 팀 · 연동 | 12자 문자열 |
| 사람 · 연동 봇 | UUID |
| 제목 속성 | `title` |
| 문서를 블록으로 읽을 때 | 문서 ID |
| 하위 문서 블록 · 인라인 데이터베이스 블록 | 그 문서 · 그 데이터베이스의 ID |
| 원본 동기화 블록 | 자기 ID입니다. 그 안의 블록은 `<동기화 블록 ID>.<블록 주소>`입니다. |
| 그 밖의 블록 | `<문서 ID>.<블록 주소>`. 형식을 해석하지 말고 받은 값을 그대로 사용하세요. |

데이터베이스와 데이터 소스는 ID가 같습니다. 속성 ID와 선택지 ID는 [데이터 소스 읽기](https://developers.bottari.ai/ko/api-reference/data-sources/retrieve.md) 응답에서 확인할 수 있습니다.

경로와 관계의 ID는 형식을 검사하지 않습니다. 형식이 틀린 ID도 없는 ID와 같이 404를 반환합니다.

## 시각

`created_time`과 `last_edited_time`은 UTC이고 분 단위로 잘립니다. `created_time`과 `last_edited_time` 필터도 이 값으로 비교합니다. 수식의 `now()`와 날짜 필터의 오늘 · 이번 주도 UTC로 계산합니다.

## 예약된 사용자 ID

`created_by`와 `last_edited_by`에는 다음 값이 올 수 있습니다.

| ID | 의미 |
| - | - |
| `00000000-0000-0000-0000-000000000000` | 작성자를 알 수 없습니다. 시스템이 만들었거나 작성자 계정이 지워졌습니다. |
| `00000000-0000-0000-0000-000000000003` | 자동화가 썼습니다. `GET /v1/users/{id}`로 읽으면 404이고 사람 속성에 넣을 수 없습니다. |

## 속성 고르기

`POST /v1/data_sources/{id}/query` · `GET /v1/pages/{id}` · `POST /v1/search`는 쿼리 문자열 `filter_properties`를 받습니다. 속성 이름이나 ID를 반복해 넣으면 그 속성만 응답에 담습니다. `filter_properties[]`로 써도 됩니다.

```text theme={null}
?filter_properties=title&filter_properties=exampleFld01
```

없는 속성을 넣으면 쿼리와 페이지 읽기는 400 `Could not find property with name or id: ...`이고, 검색은 건너뜁니다. 하위 문서에는 제목만 있습니다.

## 파일 주소

파일 속성 · 파일 블록 · 올린 그림 아이콘과 표지의 주소는 서명 주소이고 1시간 뒤 만료됩니다. `expiry_time`을 확인하고, 지나면 다시 읽어 새 주소를 받으세요.


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