Notion
Notion과 두 가지 방법으로 대화하세요. 동일한 통합 토큰이 두 방법 모두에서 작동하며, 사용 가능한 방법에 따라 선택하세요.
◆ ntn CLI — Notion의 공식 CLI. 더 짧은 구문, 한 줄 파일 업로드, Workers에 필요함. 2026년 5월 기준 macOS + Linux만 지원(Windows 지원 "곧 제공 예정"). 설치 시 기본값입니다.
◆ HTTP + curl — Windows를 포함한 모든 곳에서 작동합니다. ntn이 설치되지 않은 경우 기본 대체 방법입니다.
설정
1. 통합 토큰 얻기 (두 경로 모두 필요)
- https://notion.so/my-integrations 에서 통합을 만듭니다.
- API 키를 복사합니다(
ntn_또는secret_로 시작). ~/.hermes/.env에 저장합니다:NOTION_API_KEY=ntn_여기에_키_입력- Notion에서 대상 페이지/데이터베이스를 통합과 공유합니다: 페이지 메뉴
...→연결 대상→ 통합 이름. 이 단계를 수행하지 않으면 API가 해당 페이지에 대해 404를 반환합니다(페이지가 존재함에도 불구하고).
2. ntn 설치 (macOS / Linux에서 선호)
# 권장
curl -fsSL https://ntn.dev | bash
# 또는 npm을 통해 (Node 22+, npm 10+ 필요)
npm install --global ntn
ntn --version # 확인
ntn login은 건너뛰고 대신 통합 토큰을 사용하세요. 이렇게 하면 브라우저 없이 헤드리스로 작동합니다:
export NOTION_API_TOKEN=$NOTION_API_KEY # ntn은 NOTION_API_TOKEN을 읽습니다
export NOTION_KEYRING=0 # OS 키체인을 사용하지 않음
이 export를 셸 프로필(또는 ~/.hermes/.env)에 추가하여 모든 세션이 상속받도록 합니다.
3. 런타임에 경로 선택
if command -v ntn >/dev/null 2>&1; then
# ntn 사용
else
# curl로 대체
fi
Windows 사용자: 2단계를 완전히 건너뛰고 네이티브 ntn이 출시될 때까지 기다리세요 — 경로 B가 잘 작동합니다. 현재 CLI 편의성을 원한다면 WSL2 내에서 ntn을 설치하세요.
API 기본 사항
모든 HTTP 요청에는 Notion-Version: 2025-09-03이 필요합니다. ntn이 이를 자동으로 처리합니다. 이 버전에서 사용자들이 "데이터베이스"라고 부르는 것은 API에서 데이터 소스라고 합니다.
경로 A — ntn CLI (선호, macOS / Linux)
원시 API 호출 (curl의 단축 표기)
ntn api v1/users # GET
ntn api v1/pages parent[page_id]=abc123 \ # 인라인 본문으로 POST
properties[title][0][text][content]="노트"
ntn api v1/pages/abc123 -X PATCH archived:=true # PATCH; :=는 문자열이 아님(불/숫자/null)
구문 참고:
key=value— 문자열 필드key[nested]=value— 중첩 객체 필드key:=value— 타입 할당 (불리언, 숫자, null, 배열)
검색
ntn api v1/search query="페이지 제목"
페이지 메타데이터 읽기
ntn api v1/pages/{page_id}
페이지를 마크다운으로 읽기 (에이전트 친화적)
ntn api v1/pages/{page_id}/markdown
페이지 콘텐츠를 블록으로 읽기
ntn api v1/blocks/{page_id}/children
마크다운에서 페이지 생성
ntn api v1/pages \
parent[page_id]=xxx \
properties[title][0][text][content]="회의 노트" \
markdown="# 안건\n\n- Q3 로드맵\n- 채용"
마크다운으로 페이지 패치
ntn api v1/pages/{page_id}/markdown -X PATCH \
markdown="## 업데이트\n\n프로토타입을 출시했습니다."
데이터베이스(데이터 소스) 쿼리
ntn api v1/data_sources/{data_source_id}/query -X POST \
filter[property]=상태 filter[select][equals]=활성
복잡한 쿼리(sorts, 여러 필터 절, 복합 논리 포함)의 경우 JSON을 파이프로 전달하세요:
echo '{"filter": {"property": "Status", "select": {"equals": "Active"}}, "sorts": [{"property": "Date", "direction": "descending"}]}' | \
ntn api v1/data_sources/{data_source_id}/query -X POST --json -
파일 업로드 (한 줄 명령어 — CLI의 가장 큰 장점)
ntn files create < photo.png
ntn files create --external-url https://example.com/photo.png
ntn files list
3단계 HTTP 흐름(업로드 생성 → PUT 바이트 → 참조)과 비교하세요.
유용한 환경 변수
| 변수 | 효과 |
|---|---|
NOTION_API_TOKEN | 인증 토큰(키체인 재정의) — 통합 토큰으로 설정 |
NOTION_KEYRING=0 | OS 키체인 대신 ~/.config/notion/auth.json에 파일 기반 자격 증명 |
NOTION_WORKSPACE_ID | 워크스페이스 선택기 프롬프트 건너뛰기 |
경로 B — HTTP + curl (크로스 플랫폼, Windows에서 기본값)
모든 요청은 다음 패턴을 공유합니다:
curl -s -X GET "https://api.notion.com/v1/..." \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json"
Windows 10+에 포함된 curl이 그대로 작동합니다. PowerShell 사용자는 Invoke-RestMethod를 사용할 수도 있습니다.
검색
curl -s -X POST "https://api.notion.com/v1/search" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{"query": "페이지 제목"}'
페이지 메타데이터 읽기
curl -s "https://api.notion.com/v1/pages/{page_id}" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03"
페이지를 마크다운으로 읽기 (에이전트 친화적)
블록 JSON보다 모델에 제공하기 쉽습니다.
curl -s "https://api.notion.com/v1/pages/{page_id}/markdown" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03"
페이지 콘텐츠를 블록으로 읽기 (구조가 필요할 때)
curl -s "https://api.notion.com/v1/blocks/{page_id}/children" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03"
마크다운에서 페이지 생성
POST /v1/pages는 markdown 본문 매개변수를 허용합니다.
curl -s -X POST "https://api.notion.com/v1/pages" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{
"parent": {"page_id": "xxx"},
"properties": {"title": [{"text": {"content": "회의 노트"}}]},
"markdown": "# 안건\n\n- Q3 로드맵\n- 채용\n\n## 결정 사항\n- MVP 금요일 출시"
}'
마크다운으로 페이지 패치
curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}/markdown" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{"markdown": "## 업데이트\n\n프로토타입을 출시했습니다."}'
데이터베이스에 페이지 생성 (타입 속성 사용)
curl -s -X POST "https://api.notion.com/v1/pages" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{
"parent": {"database_id": "xxx"},
"properties": {
"이름": {"title": [{"text": {"content": "새 항목"}}]},
"상태": {"select": {"name": "할 일"}}
}
}'
데이터베이스(데이터 소스) 쿼리
curl -s -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{
"filter": {"property": "Status", "select": {"equals": "Active"}},
"sorts": [{"property": "Date", "direction": "descending"}]
}'
데이터베이스 생성
curl -s -X POST "https://api.notion.com/v1/data_sources" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{
"parent": {"page_id": "xxx"},
"title": [{"text": {"content": "내 데이터베이스"}}],
"properties": {
"이름": {"title": {}},
"상태": {"select": {"options": [{"name": "할 일"}, {"name": "완료"}]}},
"날짜": {"date": {}}
}
}'
페이지 속성 업데이트
curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{"properties": {"Status": {"select": {"name": "Done"}}}}'
페이지에 블록 추가
curl -s -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{
"children": [
{"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hermes에서 보낸 인사!"}}]}}
]
}'
파일 업로드 (3단계 흐름)
# 1. 업로드 생성
curl -s -X POST "https://api.notion.com/v1/file_uploads" \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json" \
-d '{"filename": "photo.png", "content_type": "image/png"}'
# 2. 위에서 반환된 upload_url에 PUT 바이트 전송
curl -s -X PUT "{upload_url}" --data-binary @photo.png
# 3. 페이지/블록 페이로드에서 {file_upload_id} 참조
속성 유형
데이터베이스 항목의 일반적인 속성 형식:
- 제목:
{"title": [{"text": {"content": "..."}}]} - 서식 있는 텍스트:
{"rich_text": [{"text": {"content": "..."}}]} - 선택:
{"select": {"name": "옵션"}} - 다중 선택:
{"multi_select": [{"name": "A"}, {"name": "B"}]} - 날짜:
{"date": {"start": "2026-01-15", "end": "2026-01-16"}} - 체크박스:
{"checkbox": true} - 숫자:
{"number": 42} - URL:
{"url": "https://..."} - 이메일:
{"email": "[email protected]"} - 관계:
{"relation": [{"id": "page_id"}]}
API 버전 2025-09-03 — 데이터베이스 vs 데이터 소스
- 데이터베이스가 데이터 소스가 되었습니다. 쿼리 및 검색에는
/data_sources/엔드포인트를 사용하세요. - 데이터베이스당 두 개의 ID:
database_id및data_source_id.- 페이지 생성 시
database_id:parent: {"database_id": "..."} - 쿼리 시
data_source_id:POST /v1/data_sources/{id}/query
- 페이지 생성 시
- 검색은 데이터베이스를
data_source_id필드와 함께"object": "data_source"로 반환합니다.
Notion Workers (고급, ntn 필요)
Workers는 Notion이 호스팅하는 TypeScript 프로그램입니다. 하나의 Worker는 다음의 모든 조합을 노출할 수 있습니다:
- 동기화 — 예약(기본 30분)에 따라 외부 API에서 Notion 데이터베이스로 데이터를 가져옵니다.
- 도구 — Notion의 사용자 지정 에이전트 내에서 호출 가능한 도구로 나타납니다.
- 웹훅 — 외부 서비스(GitHub, Stripe 등)로부터 HTTP 이벤트를 수신하여 Notion에서 작업을 수행합니다.
요금제 / 플랫폼 제한:
- CLI는 모든 요금제에서 작동합니다. Workers 배포에는 Business 또는 Enterprise가 필요합니다.
ntn은 2026년 5월 기준 macOS/Linux 전용입니다. Windows 사용자는 WSL2가 필요하거나 네이티브 지원을 기다려야 합니다.- 2026년 8월 11일까지 무료이며, 이후에는 Notion 크레딧으로 측정 사용됩니다.
최소 Worker
ntn workers new my-worker # 스캐폴드
cd my-worker
# Edit src/index.ts
ntn workers deploy --name my-worker
src/index.ts:
import { Worker } from "@notionhq/workers";
const worker = new Worker();
export default worker;
worker.tool("greet", {
title: "사용자에게 인사",
description: "친근한 인사말을 반환합니다",
inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
execute: async ({ name }) => `안녕하세요, ${name}!`,
});
웹훅 기능
worker.webhook("onGithubPush", {
title: "GitHub 푸시 핸들러",
execute: async (events, { notion }) => {
for (const event of events) {
// event.body, event.rawBody (서명 확인용), event.headers
console.log("got delivery", event.deliveryId);
}
},
});
배포 후: ntn workers webhooks list는 Notion이 생성한 URL을 보여줍니다. 해당 URL을 비밀로 취급하세요 — 서명 확인을 추가하지 않으면 URL을 가진 사람이 누구든 이벤트를 POST할 수 있습니다.
Worker 수명 주기 명령어
ntn workers deploy
ntn workers list
ntn workers exec <capability-key> -d '{"name": "world"}'
ntn workers sync trigger <key> # 지금 동기화 실행
ntn workers sync pause <key>
ntn workers env set GITHUB_WEBHOOK_SECRET=...
ntn workers runs list # 최근 호출
ntn workers runs logs <run-id>
ntn workers webhooks list
Worker를 빌드하라는 요청을 받으면 ntn workers new로 스캐폴드하고, src/index.ts에 코드를 작성하고, ntn workers env set으로 시크릿을 설정한 후 배포하세요. Notion 문서(https://developers.notion.com/workers)에서 전체 API 표면을 다룹니다.
Notion-Flavored Markdown (/markdown 엔드포인트에서 사용)
표준 CommonMark에 Notion 특정 블록을 위한 XML 유사 태그가 추가되었습니다. 들여쓰기에는 탭을 사용하세요.
CommonMark를 넘어서는 블록:
<callout icon="🎯" color="blue_bg">
금요일까지 MVP를 출시하세요.
</callout>
<details color="gray">
<summary>토글 제목</summary>
한 탭 들여쓰기된 자식 요소
</details>
<columns>
<column>왼쪽</column>
<column>오른쪽</column>
</columns>
<table_of_contents color="gray"/>
인라인:
- 멘션:
<mention-user url="..."/>,<mention-page url="...">제목</mention-page>,<mention-date start="2026-05-15"/> - 밑줄:
<span underline="true">텍스트</span> - 색상:
<span color="blue">텍스트</span>또는 첫 번째 줄의 블록 수준{color="blue"} - 수학: 인라인
$x^2$, 블록$$ ... $$ - 인용:
[^https://example.com]
색상: gray brown orange yellow green blue purple pink red, 배경용 *_bg 변형.
제목 5/6은 H4로 축소됩니다. 여러 > 줄은 별도의 인용 블록으로 렌더링됩니다 — 여러 줄 인용을 위해서는 단일 > 안에서 <br>을 사용하세요.
올바른 경로 선택
| 작업 | mac / Linux | Windows |
|---|---|---|
| 페이지 읽기/쓰기, 검색, 데이터베이스 쿼리 | ntn api ... | curl |
| 요약할 에이전트를 위해 페이지 읽기 | ntn api v1/pages/{id}/markdown | curl /markdown 엔드포인트 |
| 파일 업로드 | ntn files create < file | 3단계 HTTP 흐름 |
| 일회성 API 탐색 | ntn api ... | curl |
| Notion이 호스팅하는 동기화/웹훅/에이전트 도구 빌드 | ntn workers ... | WSL2 + ntn workers ... |
참고 사항
- 페이지/데이터베이스 ID는 UUID입니다(대시 포함 또는 미포함 — 둘 다 허용).
- 속도 제한: 초당 약 3회 요청. CLI는 이를 우회하지 않습니다.
- API는 데이터베이스 보기 필터를 설정할 수 없습니다 — UI 전용입니다.
- 데이터 소스를 생성할 때
"is_inline": true를 사용하여 페이지에 임베드하세요. - 항상
-s를 curl에 전달하여 진행률 표시줄을 숨기세요(더 깔끔한 에이전트 출력). - 읽을 때는 JSON을
jq로 파이프하세요:... | jq '.results[0].properties'. - Notion은 현재 MCP 서버도 제공합니다 (`Notion …