Notion API 데이터베이스 생성
Notion API 데이터베이스 생성
Notion API로 워크스페이스에 새 데이터베이스를 만들 수 있어요. POST /v1/databases 엔드포인트를 호출하면 지정한 부모 페이지(parent page) 아래에 데이터베이스를 서브페이지로 생성해요. 요청 본문에 parent와 title, 그리고 컬럼 구조를 정의하는 properties 스키마를 함께 보내면 돼요.
출처: 문서
본문
핵심 기능
POST https://api.notion.com/v1/databases 요청으로 데이터베이스를 만들어요. 만들어진 데이터베이스의 부모는 반드시 Notion 페이지나 위키 데이터베이스(wiki database)여야 해요.
이 엔드포인트는 연결(connection)에 콘텐츠 삽입(insert content) 기능이 있어야 해요. 삽입 기능이 없는 연결로 호출하면 403 상태 코드를 반환해요.
오류(Errors):
- 부모 페이지가 없거나 연결이 부모 페이지에 접근할 수 없으면
404를 반환해요. - 요청 형식이 잘못되면
400을, 요청 한도를 초과하면429를 반환해요.
권한(Authorization):
Authorization 헤더에 Bearer <token> 형태로 인증 토큰을 넣어요.
헤더(Headers):
Notion-Version 헤더에 사용할 API 버전을 지정해야 해요. 최신 버전은 2026-03-11이에요.
요청 본문(Body) 주요 필드:
parent(required): 데이터베이스를 만들 부모 페이지(Page Id) 객체예요.title: 데이터베이스의 제목이에요. 최대 100개 항목까지 지정할 수 있어요.description: 데이터베이스의 설명이에요. 최대 100개 항목까지 지정할 수 있어요.is_inline: 데이터베이스를 부모 페이지에 인라인으로 표시할지 여부예요. 기본값은false예요.database_type:tasks,projects,skills중 하나로, Notion의 표준 스키마(캐노니컬 스키마)로 데이터베이스를 만들어요.initial_data_source와 함께 쓸 수 없고,title을 생략하면 타입 이름으로 데이터베이스 이름이 정해져요.icon: 데이터베이스의 아이콘이에요.cover: 데이터베이스의 커버 이미지예요.
사용 예시
TypeScript SDK로 만드는 가장 간단한 예시예요:
import { Client } from "@notionhq/client"
const notion = new Client({ auth: process.env.NOTION_API_KEY })
const response = await notion.databases.create({
parent: {
type: "page_id",
page_id: "b55c9c91-384d-452b-81db-d1ef79372b75"
},
title: [{ text: { content: "My Database" } }]
})
curl로는 이렇게 호출해요:
curl --request POST \
--url https://api.notion.com/v1/databases \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Notion-Version: <notion-version>' \
--data '
{
"parent": {
"type": "page_id",
"page_id": "<string>"
},
"title": [
{
"text": {
"content": "<string>",
"link": {
"url": "https://www.notion.com"
}
},
"annotations": {
"bold": true,
"italic": true,
"strikethrough": true,
"underline": true,
"code": true
},
"type": "text"
}
],
"description": [
{
"text": {
"content": "<string>",
"link": {
"url": "https://www.notion.com"
}
},
"annotations": {
"bold": true,
"italic": true,
"strikethrough": true,
"underline": true,
"code": true
},
"type": "text"
}
],
"is_inline": true,
"initial_data_source": {
"properties": {}
},
"icon": {
"file_upload": {
"id": "<string>"
},
"type": "file_upload"
},
"cover": {
"file_upload": {
"id": "<string>"
},
"type": "file_upload"
}
}
'
응답(Response)
성공하면 200과 함께 데이터베이스 객체를 반환해요:
{
"object": "database",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}