<aside> ❗ Notion 팁: 이 템플릿을 활용해 Notion에서 API 레퍼런스를 작성하고 호스팅해 보세요. 엔드포인트 데이터베이스에는 추가 문서를 위한 엔드포인트 템플릿도 포함되어 있습니다.

</aside>

기본 정보

시작하기

이 문서는 Notion API에 대한 전반적 이해를 돕는 것을 목적으로 합니다.

<aside> ❗ Notion API를 사용하려면 토큰이 필요합니다. 토큰은 연결 설정 페이지에서 연결을 생성한 후 받을 수 있습니다. Notion API를 처음 사용한다면, 시작하기 가이드를 통해 연결 생성 방법을 알아보세요.

</aside>

규칙

모든 API 요청을 전송하는 기본 URL은 https://api.notion.com입니다. 모든 API 요청에는 HTTPS가 필요합니다.

Notion API는 페이지와 데이터베이스 리소스에 대한 GET, POST, PATCH, DELETE 요청을 통해 대부분 작업을 수행하는 등 가능한 한 RESTful 규칙을 따릅니다. 요청과 응답 본문은 JSON으로 인코딩됩니다.

JSON 규칙

• 최상위 리소스에는 "object" 속성이 있습니다. 이 속성은 리소스의 유형을 결정하는 데 사용할 수 있습니다(예: ”database", "user" 등).
• 최상위 리소스는 UUIDv4 "id" 속성으로 주소를 지정할 수 있습니다. Notion URL에서 ID를 복사할 때와 같이 API에 요청할 때 ID에서 대시를 생략할 수 있습니다.
• 속성 이름은 Camel Case나 Kebab Case가 아닌 Snake Case로 되어 있습니다.
• 시간 값(날짜와 일시)은 ISO 8601 문자열로 인코딩됩니다. 일시는 시간 값(2020-08-12T02:12:33.231Z)을 포함하며, 날짜는 날짜(2020-08-12)만 포함합니다.
• Notion API는 빈 문자열을 지원하지 않습니다. 예를 들어, url 속성값 개체와 같은 속성의 문자열 값을 설정 해제하려면 "" 대신 명시적인 null을 사용하세요.

코드 샘플과 SDK

각 엔드포인트의 샘플 요청과 응답이 표시됩니다. 요청은 Notion JavaScript SDK, cURL을 사용하여 표시됩니다. 샘플을 사용하면 연결을 개발할 때 쉽게 복사, 붙여넣기, 수정할 수 있습니다.

Notion SDK는 설치하여 쉽게 개발할 수 있는 오픈 소스 프로젝트입니다. HTTP 요청을 할 수 있는 다른 언어나 라이브러리를 선택할 수도 있습니다.

페이지네이션

객체 목록을 조회하는 엔드포인트는 커서 기반 페이지네이션 요청을 지원합니다. 기본적으로 Notion은 API 호출당 10개의 항목을 조회합니다. 지원되는 엔드포인트의 응답에 포함된 항목 수가 기본값을 초과하는 경우, 연결에서 페이지네이션을 사용하여 특정 결과를 요청하거나 조회되는 항목 수를 제한할 수 있습니다.

지원되는 엔드포인트

응답

요청 제한

모든 API 사용자에게 공평한 경험을 보장하기 위해 Notion API는 요청 속도 제한이 적용되며 요청 파라미터에 사이즈 제한이 적용됩니다.

속도 제한

속도가 제한된 요청은 "rate_limited" 오류 코드(HTTP 응답 상태 429)를 반환합니다. 통합당 요청에 대한 속도 제한은 초당 평균 3건입니다. 평균 속도를 초과하는 일부 버스트는 허용됩니다.

<aside> ❗ 속도 제한은 변경될 수 있습니다.

앞으로는 수요와 안정성의 균형을 맞추기 위해 전송률 한도를 조정할 계획입니다. 또한 요금제에 따라 워크스페이스에 별도의 속도 제한이 도입될 수 있습니다.

</aside>

사이즈 제한

Notion은 요청 시 특정 파라미터의 크기와 children의 깊이를 제한합니다. 이러한 제한을 초과하는 요청은 "validation_error" 오류 코드(HTTP 응답 상태 400)를 반환합니다. 더 구체적인 세부 정보는 "message" 속성에서 확인할 수 있습니다.

상태 코드

HTTP 응답 코드는 일반적인 성공과 오류 클래스를 나타내는 데 사용됩니다.

성공 코드

오류 코드

오류 응답 본문의 “code"와 "message" 속성에서 오류에 대한 더 구체적인 세부 정보를 확인할 수 있습니다.

버전

Notion의 API 버전은 버전이 론칭된 날짜에 따라 이름이 지어집니다. 예를 들어, 최신 버전은 2022-06-28입니다.

버전은 Notion-Version 헤더를 포함하여 설정합니다. Required에서 Notion-Version 헤더를 설정하세요.

curl <https://api.notion.com/v1/users/01da9b00-e400-4959-91ce-af55307647e5> \\
  -H "Authorization: Bearer secret_t1CdN9S8yicG5eWLUOfhcWaOscVnFXns"
  -H "Notion-Version: 2022-06-28"

객체

사용자

사용자 객체가 API에 나타나는 위치

사용자 객체는 다음을 포함해 API에서 반환되는 거의 모든 객체에 표시됩니다.

• 생성자, 최종 편집자 속성의 블록 객체
• 생성자, 최종 편집자 , 사람 속성의 페이지 객체
• 생성자, 최종 편집자 속성의 데이터베이스 객체
• 사용자가 멘션 시 서식 있는 텍스트 객체
• 사람 속성에서 속성 객체

사용자 객에는 아래 설명된 대로 object와 id 키가 항상 포함됩니다. 사용자가 서식 있는 텍스트나 페이지 속성 컨텍스트에서 렌더링되고, 봇이 해당 속성에 액세스할 수 있는 올바른 기능이 있는 경우 나머지 속성이 표시될 수 있습니다. 기능에 대한 자세한 내용은 기능 가이드와 인증 가이드를 참고하세요.

모든 사용자

이 필드는 사람과 봇을 포함한 모든 사용자에 적용됩니다. *이 표시된 필드는 항상 존재하는 속성입니다.

파일

파일 객체에는 Notion에 업로드된 파일에 대한 데이터 또는 Notion에서 링크된 외부 파일에 대한 데이터가 포함되어 있습니다.

{
  "type": "file",
  "file": {
    "url": "<https://s3.us-west-2.amazonaws.com/secure.notion-static.com/7b8b0713-dbd4-4962-b38b-955b6c49a573/My_test_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20221024%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221024T205211Z&X-Amz-Expires=3600&X-Amz-Signature=208aa971577ff05e75e68354e8a9488697288ff3fb3879c2d599433a7625bf90&X-Amz-SignedHeaders=host&x-id=GetObject>",
    "expiry_time": "2022-10-24T22:49:22.765Z"
  }
}

페이지, 임베드, 이미지, 동영상, 파일, PDF, 북마크 블록 유형에는 모두 파일 객체가 포함되어 있습니다. 아이콘과 표지 페이지 객체 값에도 파일 객체가 포함되어 있습니다.

각 파일 객체에서 다음 필드를 확인할 수 있습니다.

엔드포인트

엔드포인트