Notionの使い方とNotion API｜データベース設計とPython実例

Notionの中身は「ページ」の入れ子です。ページは段落や見出しなどの「ブロック」でできていて、データベースの1行も1つのページです。Notion APIは、その行（ページ）を外から作ったり探したりします。

flowchart TD
    W[ワークスペース] --> P[ページ<br>文書1枚]
    P --> B[ブロック<br>段落・見出しなど]
    P --> D[データベース<br>表・ボードなど]
    D -->|画面でも API でも<br>追加・検索・更新| R[行も1つのページ<br>プロパティ付き]

やりたいことと、Notionの画面での操作・APIでの操作の対応です。

やりたいこと	画面での操作	APIでの操作
文書を書く	ページを作り / でブロックを足す	POST /v1/pages
タスクを管理する	データベース＋ボードビュー	POST /v1/pages（行の追加）
条件で探す	ビューのフィルター・並べ替え	POST /v1/data_sources/{id}/query
表同士をつなぐ	リレーション・ロールアップ	relation プロパティ
決まった形で作る	データベーステンプレート	template パラメータ
人に見せる	「共有」から招待	ページに「コネクションを追加」
書き出す	••• → エクスポート	GET /v1/pages/{id}/markdown

確認環境：Ubuntu 24.04・Python 3.11.15・notion-client 3.1.0（PyPI、httpx 0.28.1）・curl 8.5.0・@notionhq/client 5.27.1（npm、既定の版の確認のみ）。Notion API の代わりに、公式リファレンスの形で応答する擬似サーバーを手元に立て、curl と notion-client を向けて、実際に送られた URL・ヘッダー・JSON と、エラー時・429 時の SDK の動きを記録しました。Notion の実際のエラー応答の文面は、notion-sdk-py のテストに記録された Notion API の応答（2026年7月記録）で確かめています。画面の操作・料金・プランは Notion の公式サイトとヘルプセンター（日本語版）、API の仕様・エラーコード・上限・Notion-Version は developers.notion.com のドキュメントで確かめました（確認日 2026年10月22日）。

Notionとは（ページ・ブロック・データベース）

この節では、Notionが何をするツールで、どんな部品でできているかが分かります。

Notion（ノーション）は、文書・Wiki・タスク管理・データベースを1つのワークスペースにまとめるアプリです。 Web ブラウザ、デスクトップアプリ（Mac・Windows）、モバイルアプリで使え、同じページを複数人で同時に編集できます。

エンジニアのチームでは、次のような使い方が多く見られます。

用途	Notionで作るもの	使う機能
タスク管理	タスクのデータベース	ボードビュー・ステータス・担当
設計メモ・ADR	設計判断のデータベース	テンプレート・リレーション
議事録	会議のデータベース	繰り返しテンプレート・ToDo
社内Wiki・手順書	ページの階層	見出し・コードブロック・目次
学習ノート・技術メモ	ページかデータベース	タグ・検索

Notionの料金プランと無料プランの制限

この節では、どのプランで何ができるかと、無料プランの制限が分かります。

Notion の料金ページの表示です（2026年10月22日時点。金額は米ドル、メンバー1人あたり・月額）。料金ページには月払い・年払いの切り替えがあり、「年間プランで最大20%お得」と表示されています。

プラン	料金	主な違い
フリー	$0	個人ならブロック無制限。2人以上はブロック数に上限
プラス	$10	ブロック無制限・ページ履歴30日・チャート無制限
ビジネス	$20	Notionエージェント・AI議事録・SAML SSO・ページ履歴90日
エンタープライズ	要問い合わせ	SCIM・監査ログ・ページ履歴無制限

無料プランの主な制限は次のとおりです（同じく2026年10月22日時点）。

• ブロック数：個人で使う限り無制限。メンバーが2人以上になると上限があり、上限に達すると新しいブロックを足せなくなります（閲覧・編集はできます）。
• ファイル：画像・動画・添付ファイルは1つ5MBまで。
• ページ履歴：7日間。
• ゲスト：10人まで。
• Notion AI：フリー・プラスは試用（回数に制限あり）。

学生・教職員は、教育機関のメールアドレスで登録するとプラス相当の機能を無料で使える、と料金ページに書かれています。Notion API はフリープランでも使えます。 API ドキュメントのレート制限の表には、ビジネス・エンタープライズと「その他のプラン」の上限が載っていて、プランで変わるのは1分あたりの回数です。

Notionの始め方（アカウント・アプリ・日本語化）

この節では、アカウントを作ってから最初のページを作るまでの流れが分かります。

ほかのツールから移るときは、サイドバーの「設定」→「インポート」から取り込めます。Markdown・テキスト・CSV（データベースになる）・HTML・Word・PDF・ZIP のほか、Google ドキュメント・Confluence・Evernote・Trello などに対応しています。

ページとブロックの使い方（Markdown記法・スラッシュコマンド）

この節では、ページの書き方と、よく使う入力のしかたが分かります。

ブロックは /（スラッシュ）で呼び出すか、行頭に Markdown 風の記号を打って作ります。 ヘルプセンターのショートカット一覧から、よく使うものを抜き出しました。

打つもの	できるブロック	補足
# ## ### ＋スペース	見出し1・2・3	行頭で入力
- * + ＋スペース	箇条書き	1. で番号付き
[]	ToDo（チェックボックス）	記号の間にスペースは不要
> ＋スペース	トグル（折りたたみ）	引用は " ＋スペース
---	区切り線	―
/code	コードブロック	言語を選ぶと色分けされる
/toc	目次	見出しから自動で作られる
/todo /toggle /quote	ToDo・トグル・引用	/ の後に名前で検索できる
` で囲む	インラインコード	** で太字、~ で取り消し線

よく使うキーは次のとおりです（Mac は Cmd、Windows は Ctrl）。

キー	動き
Cmd／Ctrl ＋ P（または K）	検索・最近のページを開く
Cmd／Ctrl ＋ N	新しいページ
Cmd／Ctrl ＋ L	ページの URL をコピー
Cmd／Ctrl ＋ Shift ＋ L	ダークモードの切り替え
Cmd／Ctrl ＋ [ ／ ]	前のページへ戻る・進む

データベースの使い方（ビュー・プロパティ）

この節では、データベースの「ビュー」と「プロパティ」が何で、どう選ぶかが分かります。

データベースは、同じ形のページを集めた表です。 列にあたるものを「プロパティ」、見え方を「ビュー」と呼びます。1つのデータベースに、テーブル・ボード・カレンダーなど複数のビューを持たせられ、どのビューでも中身（行）は同じです。

ビューの種類

ビューは、データベース名かビュー名の横の「＋」から追加します。

ビュー	見え方	向いている用途
テーブル	行と列の表	一覧・一括編集
ボード	プロパティの値ごとの列（カンバン）	ステータス別のタスク管理
カレンダー	日付プロパティで月の表に並ぶ	期限・リリース日・会議
タイムライン	期間を横棒で並べる	スケジュール・ガントチャート
リスト	最小限の一覧	ドキュメントの目次
ギャラリー	カードと画像	画面設計・デザイン案
チャート	棒・折れ線・ドーナツのグラフ	件数の集計

ビューの設定には「フィルター」「並べ替え」「グループ」「サブグループ」があります。設定はビューごとに保存され、ほかの人にも同じ形で見せるときは「全員に保存」を選びます。ボードビューで列を作業の段階に分ける考え方は、関連記事「カンバン方式のやり方 列の例とWIP制限の決め方・計算例」で扱っています。

プロパティの種類（22種）

ヘルプセンターの日本語版に載っているプロパティの種類です。API での型名（type）も並べました。

プロパティ	入れるもの	API の type
タイトル	行の名前（必ず1つ）	title
テキスト	書式付きの文章	rich_text
数値	数字（通貨・進捗バーでも表示）	number
選択	一覧から1つ	select
マルチセレクト	一覧から複数	multi_select
ステータス	未着手・進行中・完了のグループ	status
日付	日付・期間・時刻	date
ユーザー	ワークスペースの人・グループ	people
ファイル＆メディア	ファイル・画像	files
チェックボックス	オン・オフ	checkbox
URL・メールアドレス・電話	リンク・宛先	url・email・phone_number
数式	他のプロパティから計算	formula
リレーション	別のデータベースの行	relation
ロールアップ	リレーション先の値の集計	rollup
作成日時・作成者	自動で記録（編集不可）	created_time・created_by
最終更新日時・最終更新者	自動で更新（編集不可）	last_edited_time・last_edited_by
ボタン	1クリックで決まった操作	button
ID	行ごとの連番（編集不可）	unique_id
場所	住所・場所の名前	―

（ヘルプの一覧の22種に、どのデータベースにも1つある「タイトル」を加えています。URL・メールアドレス・電話と、作成・更新の4つは、それぞれ1行にまとめています。）

データベーステンプレートと繰り返し

データベース右上の「新規」の横の矢印から「＋新規テンプレート」を選ぶと、行を作るときのひな形（プロパティの初期値と本文）を作れます。テンプレートの横の「•••」→「繰り返し」で、毎日・毎週・毎月・毎年の間隔と開始日・時刻を決めると、そのテンプレートから行が自動で作られます。定例会議の議事録を毎週用意するときに使えます。

リレーションとロールアップの使い方

この節では、2つのデータベースをつなぐリレーションと、つないだ先を集計するロールアップの作り方が分かります。

リレーションは、別のデータベースの行を指すプロパティです。ロールアップは、リレーションでつないだ先の値を数えたり合計したりするプロパティです。 データベースでいう外部キーと集計関数に近いものです。

flowchart TD
    T[タスク DB<br>見積 h・ステータス] -->|リレーション| S[スプリント DB]
    S -->|ロールアップ<br>見積を合計| SUM[スプリントの<br>見積の合計]

作り方は次のとおりです（ヘルプセンターの手順）。

1. スプリントのデータベースにプロパティを足し、種類で「リレーション」を選ぶ。
2. つなぐ先（タスクのデータベース）を検索して選ぶ。
3. 「タスク DB に表示」のトグルをオンにすると、タスク側にもスプリントを指すプロパティができる（双方向）。
4. 青い「リレーションを追加」で確定する。
5. さらにプロパティを足し、種類で「ロールアップ」を選んで、リレーション・対象のプロパティ（見積 h）・計算（合計）を指定する。

ロールアップで選べる計算です。

対象	計算
どのプロパティでも	オリジナルを表示する・一意の値を表示する・すべてカウント・値の数をカウント・一意の値の数をカウント・未入力をカウント・未入力以外をカウント・未入力の割合・未入力以外の割合
数値だけ	合計・平均・中央値・最小・最大・範囲
日付だけ	日付の最小・最大（最も新しい日付など）・期間

ヘルプセンターには、2つのデータベースの間のリレーションは既定では一方向であること、ロールアップのロールアップは循環を防ぐためにできないこと、データベースを複製すると双方向の同期が一方向に変わることが書かれています。

開発チームでのNotionの使い方（タスク管理・設計メモ・議事録）

この節では、エンジニアのチームでそのまま使えるデータベースの構成例が3つ分かります。どれも、この後の API の節で同じ名前のプロパティを使います。

タスク管理のデータベース

プロパティ	種類	値の例
タスク名	タイトル	ログインAPIの設計
ステータス	ステータス	未着手・進行中・完了
担当	ユーザー	佐藤
期限	日付	2026-10-30
優先度	選択	高・中・低
タグ	マルチセレクト	API・設計・CI
見積(h)	数値	3
スプリント	リレーション	Sprint 12

ビューは「ボード（ステータス別）」「テーブル（自分の担当、フィルター：担当に自分を含む）」「カレンダー（期限）」の3つを用意しておくと、日々の確認・自分の作業・締め切りの確認が1つのデータベースで済みます。タスクの本文に何を書くかは、関連記事「チケットの書き方｜タスク・課題のテンプレートと良い例・悪い例」で扱っています。

設計メモ（ADR）のデータベース

設計の判断を1件1ページで残す形です。テンプレートの本文に見出しを用意しておくと、書く人によって形がばらつきません。

## 背景
（何に困っていて、何を決める必要があったか）

## 決定
（選んだ方式を1文で）

## 選んだ理由
- 

## 選ばなかった案
| 案 | 選ばなかった理由 |
|---|---|

## 影響・やること
- [ ] 

プロパティは「タイトル」「状態（選択：提案・承認・置き換え済み）」「決定日（日付）」「関連タスク（リレーション）」の4つ程度にします。

議事録のデータベース

プロパティ	種類	値の例
会議名	タイトル	2026-10-22 定例
日付	日付	2026-10-22
種類	選択	定例・設計レビュー・振り返り
参加者	ユーザー	佐藤・鈴木
関連タスク	リレーション	ログインAPIの設計

本文のテンプレートは「目的」「決まったこと」「ToDo（担当・期限つき）」「次回」の4つの見出しにし、定例は「繰り返し」で毎週自動で作ります。決まったことの ToDo をタスクのデータベースへ登録する作業は、後の節の API でまとめて行えます。

• 1データベースは用途ごとに1つ（タスク・設計メモ・議事録）同じ種類のものを複数のデータベースに分けず、ビューとフィルターで分ける
• 2進み具合はステータス、分類は選択・マルチセレクト値の候補を決めておくと、API の検索条件もぶれない
• 3プロパティ名を途中で変えないAPI はプロパティ名で値を送る。名前を変えると送る側のコードも直すことになる
• 4本文の形はテンプレートに入れる議事録・ADR の見出しを揃えると、検索と読み返しが速くなる

共有と権限（メンバー・ゲスト・Web公開）

この節では、ページを人に見せるときの権限の種類が分かります。

ページ上部の「共有」から、メンバーやグループを選ぶか、ワークスペースの外の人ならメールアドレスで招待します（ゲスト）。名前の横で権限を選び、「招待」を押します。「公開」タブからは Web に公開できます。

権限	できること
フルアクセス権限	編集と、ほかの人への共有
編集権限	編集（共有はできない）
コンテンツ編集権限	データベースの行の作成・編集だけ（構造・ビューは変えられない）
作成可能	データベースの新しい行の作成だけ（ビジネス以上）
コメント権限	コメントだけ
閲覧可能	見るだけ

ゲストは、ワークスペースに属さない人（取引先など）で、自分の Notion アカウントが必要です。組織のメールドメインを持つ人は、ゲストではなくメンバーとして追加されます。

Notion APIとは（できることと全体の流れ）

この節では、Notion API で何ができ、使い始めるまでに何をするかが分かります。

Notion API は、Notion のページ・データベース・ブロック・コメント・ユーザーを HTTP で読み書きする REST API です。 すべてのリクエストを https://api.notion.com に送り、JSON でやり取りします。公式の SDK として JavaScript（@notionhq/client）があり、Python では notion-client（notion-sdk-py）がよく使われています。

できること	エンドポイント（例）
データベースの行を追加する	POST /v1/pages（親にデータソースを指定）
データベースを条件で検索する	POST /v1/data_sources/{id}/query
行のプロパティを更新する	PATCH /v1/pages/{id}
ページを Markdown で作る・読む	POST /v1/pages（markdown）・GET /v1/pages/{id}/markdown
ページに本文（ブロック）を足す	PATCH /v1/blocks/{id}/children
ワークスペースを検索する	POST /v1/search
コメントを付ける	POST /v1/comments

使い始めるまでの流れは次のとおりです。

flowchart TD
    A[コネクションを作り<br>トークンを得る] --> B[使うページに<br>コネクションを追加]
    B --> C[データベースIDから<br>データソースIDを得る]
    C --> D[行を追加・検索・更新]
    D -->|401・404| E[トークンと共有を<br>見直す]

API を手で確かめる curl の基本は、関連記事「curlコマンドの使い方｜よく使うオプションとAPIの確認方法」で扱っています。

Notion APIの準備（コネクション作成・共有・IDの調べ方）

この節では、API を呼ぶ前にやることを、公式ドキュメントの画面の名前で順に確かめます。以前「インテグレーション」と呼ばれていたものは、ドキュメントでは「コネクション（connection）」と書かれています。

トークンの種類を選ぶ

種類	作る場所	向いている用途
内部コネクション（Internal connection）	Developer portal の Internal connections	チームのワークスペースの自動化
パーソナルアクセストークン（PAT）	Developer portal の Personal access tokens	自分として動かすスクリプト・CLI
公開コネクション（OAuth）	Developer portal の connections	他の人のワークスペースに入れてもらうアプリ

内部コネクションを作ってページに追加する

コネクションは、追加されたページとその子ページしか見られません（子ページには親の権限が引き継がれます）。 追加を忘れると、ID が正しくても後で見る 404（object_not_found）になります。トークンを .env で扱う方法は、関連記事「.envの使い方と注意点｜APIキーを安全に管理する方法」で扱っています。

データベースIDとデータソースIDを調べる

データベースの URL の、?v= の前にある32文字がデータベースIDです（?v= の後ろはビューの ID）。API はハイフンの有無どちらの形でも受け付けます。

https://www.notion.so/myteam/1a2b3c4d000040008000000000000001?v=9f8e7d6c5b4a49388271605f4e3d2c1b
                             └────── データベースID（32文字） ─────┘    └──── ビューのID ────┘

Notion-Version 2025-09-03 以降、行の追加と検索に使うのは データソースID です。データベースIDで GET /v1/databases/{id} を呼ぶと、data_sources の配列に入って返ります。Notion の画面では、データベースの設定メニューの「Manage data sources」→「Copy data source ID」でもコピーできる、と公式ドキュメントにあります。

notion-client の extract_database_id で URL から ID を取り出したところ、www.notion.so の URL では取れ、app.notion.com の URL では None になりました。API が返すページの url は https://app.notion.com/p/… の形なので、その URL から ID を取るときは、末尾の32文字を正規表現で抜き出します。

>>> extract_database_id('https://www.notion.so/myteam/1a2b3c4d000040008000000000000001?v=9f8e…')
'1a2b3c4d-0000-4000-8000-000000000001'
>>> extract_page_id('https://app.notion.com/p/2026-10-22-1a2b3c4d000040008000000000000a01')
None
>>> re.findall(r'[0-9a-f]{32}', url)[-1]
'1a2b3c4d000040008000000000000a01'

curlでデータベースに行を追加・検索・更新する

この節では、curl で行を追加・検索・更新するコマンドと、実際に送られたリクエストが分かります。トークンとデータソースIDは環境変数に入れておきます。

export NOTION_TOKEN='（コネクションのトークン）'
export DATA_SOURCE_ID='1a2b3c4d-0000-4000-8000-0000000000d5'

データソースIDを取る

curl https://api.notion.com/v1/databases/1a2b3c4d000040008000000000000001 \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2026-03-11"

応答の data_sources[0].id がデータソースIDです（応答は擬似サーバーのもの。形は公式リファレンスのとおり）。

{"object": "database", "id": "1a2b3c4d-0000-4000-8000-000000000001",
 "data_sources": [{"id": "1a2b3c4d-0000-4000-8000-0000000000d5", "name": "タスク"}], "…": "…"}

行を追加する（POST /v1/pages）

親（parent）にデータソースを指定し、properties にプロパティ名ごとの値を書きます。

curl -X POST https://api.notion.com/v1/pages \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  --data '{
    "parent": { "type": "data_source_id", "data_source_id": "'"$DATA_SOURCE_ID"'" },
    "properties": {
      "タスク名": { "title": [ { "text": { "content": "ログインAPIの設計" } } ] },
      "ステータス": { "status": { "name": "未着手" } },
      "期限": { "date": { "start": "2026-10-30" } },
      "優先度": { "select": { "name": "高" } }
    }
  }'

プロパティの種類ごとの値の書き方です（公式リファレンス「Page properties」より）。

種類	送る値の形	消すとき
タイトル・テキスト	{"title": [{"text": {"content": "…"}}]}	空の配列
ステータス・選択	{"status": {"name": "未着手"}}	選択は null
マルチセレクト	{"multi_select": [{"name": "API"}]}	[]
日付	{"date": {"start": "2026-10-30", "end": null}}	null
ユーザー	{"people": [{"id": "ユーザーID"}]}	[]
数値・チェックボックス・URL	{"number": 3}・{"checkbox": true}・{"url": "…"}	null・false・null
リレーション	{"relation": [{"id": "ページID"}]}	[]

ステータスは、既にある選択肢の名前しか送れません。ユーザーとリレーションは配列で丸ごと置き換わるので、残したい値も一緒に送ります。数式・ロールアップ・作成日時などは Notion が計算する読み取り専用の値で、送れません。

条件で検索する（POST /v1/data_sources/{id}/query）

「完了以外を、期限の早い順に」取り出します。

curl -X POST "https://api.notion.com/v1/data_sources/$DATA_SOURCE_ID/query" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  --data '{
    "filter": { "property": "ステータス", "status": { "does_not_equal": "完了" } },
    "sorts": [ { "property": "期限", "direction": "ascending" } ],
    "page_size": 100
  }'

応答は results に行（ページ）の配列、has_more と next_cursor にページ送りの情報が入ります。has_more が true なら、next_cursor の値を次のリクエストの start_cursor に入れて続きを取ります。page_size の上限は100です。

{"object": "list", "results": [ … ], "next_cursor": null, "has_more": false,
 "type": "page_or_data_source", "page_or_data_source": {}}

よく使うフィルターの書き方です（公式リファレンス「Filter data source entries」より）。

絞り込み	フィルター
ステータスが完了以外	{"property": "ステータス", "status": {"does_not_equal": "完了"}}
期限が今日まで	{"property": "期限", "date": {"on_or_before": "today"}}
期限が来週	{"property": "期限", "date": {"next_week": {}}}
担当が自分	{"property": "担当", "people": {"contains": "me"}}
優先度が高か中	{"property": "優先度", "select": {"equals": ["高", "中"]}}
2つ以上の条件	{"and": [ 条件1, 条件2 ]}（or も可。入れ子は2段まで）

行を更新する（PATCH /v1/pages/{id}）

curl -X PATCH "https://api.notion.com/v1/pages/$PAGE_ID" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  --data '{ "properties": { "ステータス": { "status": { "name": "進行中" } } } }'

実際に送られたリクエスト

ホスト名だけを手元の擬似サーバーに変えて、検索の curl を実行し、サーバーが受け取ったものをそのまま記録しました。

POST /v1/data_sources/1a2b3c4d-0000-4000-8000-0000000000d5/query HTTP/1.1
Host: 127.0.0.1:29201
User-Agent: curl/8.5.0
Accept: */*
Authorization: Bearer ntn_s292_example_token
Notion-Version: 2026-03-11
Content-Type: application/json
Content-Length: 78

{"filter":{"property":"ステータス","status":{"does_not_equal":"完了"}}}

必要なヘッダーは Authorization・Notion-Version・Content-Type の3つです。日本語のプロパティ名は UTF-8 のまま送られ、Content-Length はバイト数（78）でした。

Python（notion-client）でデータベースを操作する

この節では、Python で行を追加・検索・更新する完成コードと、その実行結果が分かります。

python3 -m venv .venv
.venv/bin/pip install notion-client

入った版は notion-client 3.1.0 でした（依存の httpx は 0.28.1）。

完成コード（tasks.py）

"""Notion のタスク管理データベースに行を追加・検索・更新する（notion-client）。"""
import os
from notion_client import Client
from notion_client.helpers import collect_paginated_api

notion = Client(
    auth=os.environ["NOTION_TOKEN"],
    notion_version="2026-03-11",
    base_url=os.environ.get("NOTION_BASE_URL", "https://api.notion.com"),
)
DATABASE_ID = os.environ["NOTION_DATABASE_ID"]

# 1. データベースID → データソースID（2025-09-03 以降は行の追加・検索にこちらを使う）
db = notion.databases.retrieve(database_id=DATABASE_ID)
ds_id = db["data_sources"][0]["id"]
print("data_source_id:", ds_id)

# 2. 行（ページ）を追加する
def add_task(name, status, due, priority, tags=(), hours=None):
    props = {
        "タスク名": {"title": [{"text": {"content": name}}]},
        "ステータス": {"status": {"name": status}},
        "期限": {"date": {"start": due}},
        "優先度": {"select": {"name": priority}},
        "タグ": {"multi_select": [{"name": t} for t in tags]},
    }
    if hours is not None:
        props["見積(h)"] = {"number": hours}
    return notion.pages.create(
        parent={"type": "data_source_id", "data_source_id": ds_id},
        properties=props,
    )

page = add_task("ログインAPIの設計", "未着手", "2026-10-30", "高", ["API", "設計"], 3)
add_task("議事録テンプレートの整備", "進行中", "2026-10-24", "中", ["ドキュメント"])
add_task("CIのキャッシュ設定", "完了", "2026-10-20", "低", ["CI"], 1)
print("created:", page["id"], page["url"])

# 3. 完了以外を期限の早い順に取り出す（ページ送りは collect_paginated_api に任せる）
rows = collect_paginated_api(
    notion.data_sources.query,
    data_source_id=ds_id,
    filter={"property": "ステータス", "status": {"does_not_equal": "完了"}},
    sorts=[{"property": "期限", "direction": "ascending"}],
    page_size=1,
)
for r in rows:
    p = r["properties"]
    print(p["期限"]["date"]["start"], p["ステータス"]["status"]["name"],
          p["タスク名"]["title"][0]["plain_text"])

# 4. ステータスを更新する
notion.pages.update(page_id=page["id"], properties={"ステータス": {"status": {"name": "進行中"}}})
print("updated:", page["id"])

page_size=1 は、ページ送りの動きを見るためにわざと小さくしています。普段は省略します（既定は100件）。

実行結果

NOTION_BASE_URL を擬似サーバーに向けて実行しました。

$ python tasks.py
data_source_id: 1a2b3c4d-0000-4000-8000-0000000000d5
created: 950f3d00-733d-4c94-8eaa-e648b70c508b https://app.notion.com/p/950f3d00733d4c948eaae648b70c508b
2026-10-24 進行中 議事録テンプレートの整備
2026-10-30 未着手 ログインAPIの設計
updated: 950f3d00-733d-4c94-8eaa-e648b70c508b

擬似サーバーが受け取ったリクエストは7件でした。

順	メソッドとパス	中身
1	GET /v1/databases/1a2b…0001	本文なし
2〜4	POST /v1/pages	3行分の parent と properties
5	POST /v1/data_sources/…/query	filter・sorts・page_size: 1
6	POST /v1/data_sources/…/query	5 と同じ＋start_cursor
7	PATCH /v1/pages/950f…	{"properties": {"ステータス": {"status": {"name": "進行中"}}}}

1回目の検索に start_cursor は入らず、2回目に前の応答の next_cursor が入りました。collect_paginated_api が has_more を見て、続きを取りに行っています。2件目の POST /v1/pages で送られた本文です。

{
  "parent": { "type": "data_source_id", "data_source_id": "1a2b3c4d-0000-4000-8000-0000000000d5" },
  "properties": {
    "タスク名": { "title": [ { "text": { "content": "ログインAPIの設計" } } ] },
    "ステータス": { "status": { "name": "未着手" } },
    "期限": { "date": { "start": "2026-10-30" } },
    "優先度": { "select": { "name": "高" } },
    "タグ": { "multi_select": [ { "name": "API" }, { "name": "設計" } ] },
    "見積(h)": { "number": 3 }
  }
}

同じ検索を SDK で送ったときのヘッダーは次のとおりで、curl との違いは User-Agent: ramnes/notion-sdk-py@3.1.0・Accept-Encoding: gzip, deflate・Connection: keep-alive が付く点でした。本文（78バイト）は curl と同じです。

応答から値を取り出す

応答のプロパティは、種類ごとに入れ物の形が違います（公式リファレンスの例より）。

"ステータス": { "id": "stat", "type": "status",
                "status": { "id": "330aeafb-…", "name": "完了", "color": "green" } },
"期限":       { "id": "dueD", "type": "date",
                "date": { "start": "2026-10-30", "end": null, "time_zone": null } },
"タスク名":   { "id": "title", "type": "title",
                "title": [ { "type": "text", "plain_text": "ログインAPIの設計", "…": "…" } ] }

type を見て取り出す関数を1つ作っておくと、表示や CSV 出力が楽になります。

def value(prop):
    t = prop["type"]
    v = prop[t]
    if t in ("title", "rich_text"):
        return "".join(x["plain_text"] for x in v)
    if t in ("status", "select"):
        return v["name"] if v else None
    if t == "multi_select":
        return [x["name"] for x in v]
    if t == "date":
        return v["start"] if v else None
    if t == "people":
        return [x["id"] for x in v]
    return v  # number・checkbox・url など

Notion-Versionとデータソース（2025-09-03以降の変更）

この節では、Notion-Version ヘッダーに何を書くかと、以前の記事のコードが動かない理由が分かります。

Notion-Version は、どの版の API 仕様で処理するかを決める必須のヘッダーです。 付けないと 400 の missing_version になります。2026年10月22日時点で、API リファレンスのページ作成の項は現在の版を 2026-03-11 としています。

版	主な変更
2021-05-13	文章のプロパティの型名が text から rich_text に
2022-06-28	JavaScript SDK v5 が対応する最も前の版
2025-09-03	1つのデータベースに複数のデータソース。検索は /v1/data_sources/{id}/query に
2026-03-11	archived が in_trash に、ブロック追加の after が position に、transcription ブロックが meeting_notes に

データベースとデータソースの関係

2025-09-03 から、データベースは「入れ物」、データソースは「行とプロパティの定義を持つ表」に分かれました。1つのデータベースに複数のデータソースを持てます。

flowchart TD
    DB[データベース<br>database_id] --> DS1[データソース1<br>data_source_id]
    DB --> DS2[データソース2<br>別のプロパティ定義]
    DS1 --> P[行 = ページ<br>page_id]

2025-09-03 より前の版（2022-06-28 など）では、検索は /v1/databases/{id}/query、行の追加の親は database_id でした。公式のアップグレードガイドには、以前の版のまま使っていると、ユーザーがそのデータベースにデータソースを追加した時点で、データベースを親にしたページ作成・データベースの検索・そのデータベースを指すリレーションの書き込みが失敗する、とあります。

notion-client 3.1.0 には databases.query が無く、以前の記事のコードをそのまま動かすと次のエラーになりました。

AttributeError: 'DatabasesEndpoint' object has no attribute 'query'

notion.data_sources.query(data_source_id=…) に書き換えます。

SDK の既定の版に注意

版を指定せずに Client を作ると、送られる Notion-Version は次のとおりでした。

SDK	版	既定の Notion-Version
notion-client（Python）	3.1.0	2025-09-03
@notionhq/client（JavaScript）	5.27.1	2025-09-03

>>> Client(auth=token).client.headers["Notion-Version"]
'2025-09-03'

どちらも既定は 2025-09-03 で、2026-03-11 の仕様（in_trash・position）を使うには notion_version="2026-03-11"（JavaScript は notionVersion）を明示します。 版を明示しておくと、SDK を更新したときに知らないうちに版が変わることも防げます。

Markdownでページを作る（議事録の自動作成）

この節では、ブロックの JSON を組み立てずに、Markdown の文字列でページを作る方法が分かります。

ページ作成の markdown パラメータに Markdown を渡すと、API が見出し・箇条書き・ToDo・コードブロックなどのブロックに変換します。markdown は children・content と一緒には使えません。

curl -X POST https://api.notion.com/v1/pages \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  --data @- <<'EOF'
{
  "parent": { "page_id": "1a2b3c4d000040008000000000000a01" },
  "properties": { "title": { "title": [ { "text": { "content": "2026-10-22 定例" } } ] } },
  "markdown": "## 決まったこと\n- ログインAPIは JWT で進める\n\n## ToDo\n- [ ] API設計書を更新（佐藤）\n"
}
EOF

擬似サーバーが受け取った markdown の中身です。JSON の中では改行を \n で書きます。

## 決まったこと
- ログインAPIは JWT で進める

## ToDo
- [ ] API設計書を更新（佐藤）

公式ガイドの「Working with markdown content」による、Markdown で扱えるものと扱えないものです。

項目	内容
書ける	見出し（#〜####）・箇条書き・番号付き・ToDo（- [ ]・- [x]）・言語つきコードブロック
表	<table>・<tr>・<td> のタグで書く
読み出し	GET /v1/pages/{id}/markdown
書き換え	PATCH /v1/pages/{id}/markdown（update_content・replace_content）
変換されないもの	ブックマーク・埋め込み・リンクプレビューなどは <unknown> になる
上限	入れ子を含めて 5,000 ブロックを超えると validation_error

親を省いてワークスペース直下に作れるのは、公開コネクションとパーソナルアクセストークンだけです。内部コネクションでは、親にページかデータソースを指定します。

Notion APIのエラー（401・404・429）と直し方

この節では、Notion API が返すエラーの原文と、よくある原因・直し方が分かります。

エラーの応答は、object が "error" の JSON です。notion-sdk-py のテストに記録された、Notion API の実際の応答です。

{"object":"error","status":401,"code":"unauthorized","message":"API token is invalid.","request_id":"13dc904a-8a91-49aa-9a52-4d3926cac0af"}

{"object":"error","status":404,"code":"object_not_found","message":"Could not find page with ID: 00000000-0000-0000-0000-000000000000. Make sure the relevant pages and databases are shared with your integration \"notion-sdk-py\".","additional_data":{"integration_id":"7775f3a3-893f-43fa-b625-460c61094c78"},"request_id":"55e80b46-6675-426f-9eb0-1fa1456e4103"}

404 の文面の最後には、コネクションの名前（ここでは notion-sdk-py）が入ります。「存在しない」と「共有されていない」は、どちらも同じ 404 になります。

HTTP・code	原文（message・公式の説明）	主な原因と直し方
401 unauthorized	API token is invalid.	トークンの写し間違い・作り直す前の値。Bearer の付け忘れも確かめる
404 object_not_found	Could not find page with ID: …. Make sure the relevant pages and databases are shared with your integration "…".	ページに「コネクションを追加」していない。ID がビューの ID やデータベースIDと取り違えていないか
400 missing_version	The request is missing the required Notion-Version header.	Notion-Version ヘッダーを付ける
400 validation_error	The request body does not match the schema for the expected parameters.	プロパティ名の違い・種類の違い（status に select の形を送る等）・2,000文字を超える文字列
400 invalid_request_url	Invalid request URL.	パスの打ち間違い。/v1/ の付け忘れ
403 restricted_resource	The token lacks permission, or the request exceeds a workspace block limit.	コネクションの機能（挿入・更新）が足りない。無料プランのブロック上限
409 conflict_error	データの衝突などで完了できなかった	少し待って同じ内容でやり直す
429 rate_limited	This request exceeds the number of requests allowed. Slow down and try again.	Retry-After の秒数だけ待って再送する
503 service_unavailable	応答が60秒に間に合わなかったなど	書き込みは保存済みのことがある。additional_data.retry_guidance を見て、読み直してから判断する
529 service_overload	一時的な過負荷	Retry-After に従って再送する
Python の AttributeError	'DatabasesEndpoint' object has no attribute 'query'	data_sources.query に書き換える

（API token is invalid.・Could not find page …・Invalid request URL. は実際の応答の原文、英文のその他は公式リファレンス「Status codes」の説明、日本語は同じページの説明の要約です。）

Python でのエラーの受け取り方

notion-client は、エラーの応答を APIResponseError の例外にします。code で原因を分けられます。

from notion_client import APIResponseError, APIErrorCode

try:
    notion.pages.retrieve(page_id=page_id)
except APIResponseError as e:
    if e.code == APIErrorCode.ObjectNotFound:
        print("ページにコネクションが追加されているか確かめる:", e.request_id)
    elif e.code == APIErrorCode.Unauthorized:
        print("トークンを確かめる")
    else:
        raise

擬似サーバーに Notion と同じ文面の 401・404 を返させて実行した結果です。

401 -> 401 unauthorized | API token is invalid.
404 -> 404 object_not_found | request_id: True

429 を受けたときの SDK の自動再試行

擬似サーバーに、Retry-After: 1 付きの 429 を決まった回数だけ返させ、notion-client の動きを測りました。

試したこと	結果	かかった時間
429 が2回続いた後に成功	自動で再試行して成功	2.01秒
429 が3回続いた	APIResponseError（429 rate_limited）	2.01秒
retry=False で 429 が1回	すぐに APIResponseError（Retry-After=1）	0.00秒

notion-client 3.1.0 は、429 を最大2回まで自動で再試行し、待つ秒数は Retry-After ヘッダーに従いました。 失敗のたびに request fail: code=APIErrorCode.RateLimited, … attempt=0 の形の WARNING ログが出ます。ソースでは、500・503 の再試行は GET・DELETE だけに限られていて、POST・PATCH（追加・更新）は再試行しません。二重に登録されるのを避けるためです。再試行の回数は RetryOptions(max_retries=…) で変えられます。

再試行の作り方そのものは、関連記事「LLM APIの429・529エラー対処｜リトライ実装とエラー一覧」で扱っています。

レート制限とサイズの上限

この節では、Notion API の回数と大きさの上限が分かります（2026年10月22日時点の公式ドキュメント）。

対象	上限
1つのコネクションのリクエスト（ビジネス・エンタープライズ）	600回／分（平均 毎秒10回）
1つのコネクションのリクエスト（その他のプラン）	180回／分（平均 毎秒3回）
ワークスペース全体	すべてのコネクションで共有する別の上限あり
文字列（text.content・リンクの URL）	2,000文字
ブロックなどの配列	100個
1回のリクエストのブロック	1,000個・合計 500KB
マルチセレクトの選択肢・リレーション・ユーザー	100個・100件・100人
検索の page_size	100件

429 の応答の additional_data.rate_limit_reason を見ると、どの上限に当たったかが分かります。

rate_limit_reason	意味
public_api_request_rate_limit	そのコネクションのリクエストが速すぎる
public_api_space_request_rate_limit	ワークスペース全体の上限に当たった
public_api_endpoint_rate_limit	エンドポイントごとの上限に当たった
public_api_request_blocked	API の利用が止められている。再試行しても通らず、サポートへの連絡が要る

大量の行を入れるときは、1件ずつ送る間隔をあけ、2,000文字を超える文章は複数の rich_text に分け、100個を超えるブロックは複数回に分けて足します。

Notion MCP（AIエージェントからNotionを使う）

この節では、Claude Code などの AI エージェントから Notion を読み書きする方法が分かります。

Notion MCP は、Notion が運営している MCP サーバーです。 接続先は https://mcp.notion.com/mcp（Streamable HTTP）で、認証は OAuth です。Claude Code では次のコマンドで追加し、/mcp で OAuth の承認を済ませます。

claude mcp add --transport http notion https://mcp.notion.com/mcp

項目	内容
主なツール	notion-search・notion-query-data-sources・notion-create-pages・notion-update-page・notion-create-comment
認証	OAuth。ビジネス・エンタープライズはオーナーが MCP トークンも作れる
ローカルの notion-mcp-server	公式ドキュメントでは、現在は積極的には保守されていないとされ、Notion MCP が推奨

REST API との使い分けは、決まった処理を毎回同じ形で行うなら API、会話の中で調べたり書いたりするなら MCP、が目安です。MCP の仕組みは関連記事「MCPとは？サーバーとクライアントの仕組みと設定例を図解」で扱っています。

エクスポートとバックアップ

この節では、Notion の中身を外に書き出す方法が分かります。

ページ右上の「•••」から「エクスポート」を選び、形式を選びます。

形式	中身	補足
PDF	ページの見た目のまま	失敗したときは HTML で出力される
HTML	ZIP にまとめた HTML	コメントも含められる
マークダウンとCSV	子ページは Markdown、データベースは CSV	CSV は今のビューか既定のビューのどちらか

ワークスペース全体は「設定」→「ワークスペース」の「一般」→「ワークスペースのすべてのコンテンツをエクスポートする」から書き出せ、ダウンロードのリンクがメールで届きます（有効期限7日）。定期的に機械で取りたいときは、API の GET /v1/pages/{id}/markdown で Markdown を取り出し、Git に保存する形も取れます。

よくある質問

Q. Notionとは何ですか？何ができますか？ A. ページ（文書）とデータベース（表）を組み合わせて、メモ・Wiki・タスク管理・議事録を1つのワークスペースで扱うアプリです。データベースは表・ボード・カレンダーなどで見え方を切り替えられます。

Q. Notionは無料で使えますか？ A. 使えます。フリープランは個人ならブロック無制限で、2人以上ではブロック数に上限があり、ファイルは1つ5MBまで、ページ履歴は7日間です（2026年10月22日時点）。

Q. Notionの使い方は何から覚えればいいですか？ A. ページを作り、/ でブロックを足すところからです。次にタスクのデータベースを1つ作り、ボードビューとステータスで管理すると、データベース・ビュー・プロパティの考え方が一度に身につきます。

Q. ページとデータベースの違いは？ A. ページは文書1枚、データベースは同じ形のページを集めた表です。データベースの1行も1つのページで、本文を書けます。

Q. リレーションとロールアップの違いは？ A. リレーションは別のデータベースの行を指すプロパティ、ロールアップはリレーション先の値を数える・合計するプロパティです。ロールアップを使うには先にリレーションが要ります。

Q. Notion APIは無料で使えますか？ A. フリープランでも使えます。プランで変わるのはレート制限で、ビジネス・エンタープライズは1分600回、その他は1分180回です。

Q. Notion APIのトークン（APIキー）はどこで取得しますか？ A. Developer portal で内部コネクションを作り、Configuration タブで確かめます。自分のスクリプト用なら、Personal access tokens でパーソナルアクセストークンも作れます。

Q. Notion APIで object_not_found（404）が出ます。 A. ほとんどは、データベース（または親ページ）にコネクションが追加されていないことが原因です。ページの「•••」→「その他」→「コネクション」から追加します。ビューの ID（URL の ?v= の後ろ）を渡していないかも確かめます。

Q. Notion-Versionには何を指定しますか？ A. 2026年10月22日時点の現在の版は 2026-03-11 です。SDK の既定は 2025-09-03 だったので、使う版をコードで明示します。

Q. Notion APIでデータベースに行を追加するには？ A. POST /v1/pages に、parent としてデータソースID、properties にプロパティ名ごとの値を送ります。Python なら notion.pages.create(parent={"type": "data_source_id", "data_source_id": …}, properties=…) です。

Q. Python の notion-client で databases.query が使えません。 A. 3.x では databases.query が無くなり、data_sources.query(data_source_id=…) を使います。データソースIDは databases.retrieve の応答の data_sources にあります。

Q. NotionをMarkdownで書き出せますか？ A. 「•••」→「エクスポート」で「マークダウンとCSV」を選ぶと、ページは Markdown、データベースは CSV で書き出せます。API なら GET /v1/pages/{id}/markdown で取り出せます。

まとめ

• Notion はページ・ブロック・データベースの組み合わせ。データベースの1行も1つのページで、ビューで見え方を、プロパティで持つ値を決める。
• 料金はフリー $0・プラス $10・ビジネス $20（メンバー1人あたり月額、米ドル表示、2026年10月22日時点）。フリーは2人以上でブロック数に上限。
• 開発チームでは、タスク・設計メモ・議事録をそれぞれ1つのデータベースにし、リレーションでつなぎ、テンプレートと繰り返しで形を揃える。
• API は、コネクションを作る → ページに追加 → データベースIDからデータソースIDを得る → POST /v1/pages・POST /v1/data_sources/{id}/query の順。
• curl も SDK も、送るのは Authorization・Notion-Version・JSON の本文。SDK の既定の版は 2025-09-03 だったので、2026-03-11 を明示する。
• 401 はトークン、404 はコネクションの追加漏れ、429 は Retry-After だけ待つ。notion-client は 429 を2回まで自動で再試行した。

参考・出典

確認日はいずれも 2026年10月22日です。

• Notion「料金プラン」：https://www.notion.com/ja/pricing
• Notion ヘルプセンター「データベースのプロパティ」：https://www.notion.com/ja/help/database-properties
• Notion ヘルプセンター「ビュー、フィルター、並べ替え」：https://www.notion.com/ja/help/views-filters-and-sorts
• Notion ヘルプセンター「リレーションとロールアップ」：https://www.notion.com/ja/help/relations-and-rollups
• Notion ヘルプセンター「データベーステンプレート」：https://www.notion.com/ja/help/database-templates
• Notion ヘルプセンター「キーボードショートカット」：https://www.notion.com/ja/help/keyboard-shortcuts
• Notion ヘルプセンター「共有と権限」：https://www.notion.com/ja/help/sharing-and-permissions
• Notion ヘルプセンター「APIでコネクションを追加・管理する」：https://www.notion.com/ja/help/add-and-manage-connections-with-the-api
• Notion ヘルプセンター「言語を変更する」：https://www.notion.com/ja/help/change-your-language
• Notion ヘルプセンター「Notionにデータをインポートする」：https://www.notion.com/ja/help/import-data-into-notion
• Notion ヘルプセンター「コンテンツをエクスポートする」：https://www.notion.com/ja/help/export-your-content
• Notion「デスクトップアプリ」：https://www.notion.com/ja/desktop
• Notion Developers「Authorization」：https://developers.notion.com/docs/authorization
• Notion Developers「Internal connections」：https://developers.notion.com/guides/get-started/internal-connections
• Notion Developers「Quickstart」：https://developers.notion.com/guides/get-started/quick-start
• Notion Developers「Versioning」：https://developers.notion.com/reference/versioning
• Notion Developers「Upgrade guide 2025-09-03」：https://developers.notion.com/docs/upgrade-guide-2025-09-03
• Notion Developers「Upgrade guide 2026-03-11」：https://developers.notion.com/docs/upgrade-guide-2026-03-11
• Notion Developers「Create a page」：https://developers.notion.com/reference/post-page
• Notion Developers「Query a data source」：https://developers.notion.com/reference/query-a-data-source
• Notion Developers「Filter data source entries」：https://developers.notion.com/reference/filter-data-source-entries
• Notion Developers「Page properties」：https://developers.notion.com/reference/page-property-values
• Notion Developers「Introduction（Pagination）」：https://developers.notion.com/reference/intro
• Notion Developers「Status codes」：https://developers.notion.com/reference/status-codes
• Notion Developers「Request limits」：https://developers.notion.com/reference/request-limits
• Notion Developers「Working with markdown content」：https://developers.notion.com/guides/data-apis/working-with-markdown-content
• Notion Developers「Notion MCP」：https://developers.notion.com/docs/get-started-with-mcp
• notion-sdk-py（GitHub、tests/cassettes）：https://github.com/ramnes/notion-sdk-py
• notion-client（PyPI）：https://pypi.org/project/notion-client/
• @notionhq/client（npm）：https://www.npmjs.com/package/@notionhq/client

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。