Notion은(는) 무엇을 하나요?
공식 ntn CLI를 선호합니다. ntn을 사용할 수 없거나 원시 요청이 더 명확한 경우에만 curl을 사용하세요.
설정
npm install -g ntn
ntn --version
ntn login
스크립트/무인(headless) 인증:
export NOTION_API_TOKEN=secret_or_ntn_token
export NOTION_API_VERSION=2026-03-11
ntn api는 Authorization 및 Notion-Version을 자동으로 설정합니다. 기본적으로 CLI 로그인을 사용하며, NOTION_API_TOKEN이 설정된 경우 이를 사용합니다.
검사
ntn doctor
ntn api ls
ntn api ls --json
ntn api v1/comments --help
ntn api v1/comments --spec -X POST
ntn api v1/comments --docs -X POST
페이지
마크다운 우선 헬퍼:
ntn pages get <page-id>
ntn pages get <page-id> --json
ntn pages create --parent page:<page-id> --content '# 제목\n\n본문'
ntn pages create --parent data-source:<data-source-id> < page.md
ntn pages update <page-id> --content '# 업데이트됨'
ntn pages update <page-id> < page.md
ntn pages trash <page-id> --yes
참고 사항:
pages get은 페이지 속성을 프론트매터로 포함한 마크다운을 출력합니다.- 콘텐츠 입력:
--content, 표준 입력, 또는 TTY에서 편집기. - 상위 참조:
page:<id>,database:<id>,data-source:<id>. - 속성/템플릿/전체 페이지 API는
ntn api v1/pages를 사용하세요.
데이터 소스
ntn datasources resolve <database-id>
ntn datasources resolve <database-id> --json
ntn datasources query <data-source-id>
ntn datasources query <data-source-id> --limit 50 --json
ntn datasources query <data-source-id> --sort '날짜 desc'
ntn datasources query <data-source-id> --filter '{"property":"완료","checkbox":{"equals":true}}'
데이터베이스 ID가 있을 때는 resolve를 사용하세요. 쿼리에는 데이터 소스 ID가 필요합니다.
원시 API
ntn api v1/users/me
ntn api v1/search query=roadmap page_size:=10
ntn api v1/pages 'parent[data_source_id]='"$DS_ID" 'properties[Name][title][0][text][content]=새 항목'
ntn api "v1/pages/$PAGE_ID" -X PATCH in_trash:=true
ntn api "v1/blocks/$PAGE_ID/children" -X PATCH \
'children[0][type]=paragraph' \
'children[0][paragraph][rich_text][0][text][content]=안녕하세요'
입력 구문:
path=value: 문자열 본문 필드.path:=json: 타입이 지정된 JSON 본문 필드.name==value: 쿼리 매개변수.Header:Value: 요청 헤더.--data '<json>'또는 표준 입력 JSON (큰 본문용).- 요청당 하나의 본문 소스만 가능.
파일
ntn files create < image.png
ntn files create --filename photo.png --content-type image/png < /tmp/photo
ntn files create --external-url https://example.com/photo.png
ntn files get <upload-id>
ntn files list
Workers
ntn workers new
ntn workers deploy
ntn workers list --json
ntn workers runs list --json
ntn workers runs logs <run-id>
Workers는 Business/Enterprise 요금제와 워크스페이스 활성화가 필요할 수 있습니다.
Curl 대체
curl -sS "https://api.notion.com/v1/users/me" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json"
버전 참고 사항
- 현재 최신 API 버전:
2026-03-11. archived대신in_trash를 사용하세요.- 블록 추가 위치 지정은 평평한
after가 아닌position을 사용합니다. transcription블록이meeting_notes로 이름이 변경되었습니다.- 데이터베이스는 여러 데이터 소스를 포함할 수 있습니다. 페이지 상위 참조는 일반적으로
data_source_id를 사용합니다.