공통 규칙 - Bottari Developers

기본 주소

https://api.bottari.ai

엔드포인트는 모두 /v1/로 시작합니다.

헤더

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

응답

성공 응답의 맨 위에는 요청마다 다른 request_id가 있습니다. 문의할 때 이 값을 알려 주세요. 이 문서의 응답 예제는 예시 값을 사용합니다.

오류

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

{
  "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`	호출 횟수를 넘겼습니다. 호출 횟수 제한 자세히 알아보기 →
500	`internal_server_error`	서버 오류입니다.
503	`service_unavailable`	잠시 처리할 수 없습니다. 다시 보내세요.

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

목록 읽기

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

{
  "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로 보내세요.
커서는 그 쿼리에서만 사용할 수 있습니다. 필터나 정렬이 다른 쿼리에 보내면 400입니다.

ID

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

데이터베이스와 데이터 소스는 ID가 같습니다. 속성 ID와 선택지 ID는 데이터 소스 읽기 응답에서 확인할 수 있습니다. 경로와 관계의 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[]로 써도 됩니다.

?filter_properties=title&filter_properties=exampleFld01

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

파일 주소

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

없는 엔드포인트

다음 엔드포인트는 없습니다. 호출하면 400 invalid_request_url을 반환합니다.

묶음	엔드포인트
블록 쓰기	`PATCH /v1/blocks/{id}` · `PATCH /v1/blocks/{id}/children` · `DELETE /v1/blocks/{id}`
마크다운 쓰기	`PATCH /v1/pages/{id}/markdown`
댓글 쓰기	`POST /v1/comments` · `PATCH /v1/comments/{id}` · `DELETE /v1/comments/{id}`
파일 업로드	`/v1/file_uploads`
데이터베이스 쓰기	`POST /v1/databases` · `PATCH /v1/databases/{id}` · `POST /v1/data_sources` · `PATCH /v1/data_sources/{id}`
데이터베이스로 쿼리	`POST /v1/databases/{id}/query`. `POST /v1/data_sources/{id}/query`를 사용하세요.
기타	보기(`/v1/views`) · 템플릿 · 팀 이모지 목록 · OAuth

파일 · 아이콘 · 표지에 file_upload를 보내면 404입니다. GET /v1/users/me의 max_file_upload_size_in_bytes는 0입니다.

​기본 주소

​헤더

​응답

​오류

​목록 읽기

​ID

​시각

​예약된 사용자 ID

​속성 고르기

​파일 주소

​없는 엔드포인트