Notion APIでできること｜自作のNotion連携ツールで使った機能と、2025年からの仕様変更の注意点Notion APIでできること｜自作のNotion連携ツールで使った機能と、2025年からの仕様変更の注意点

「Notion APIって、結局なにができるの？」

ZapierやMakeの画面でNotionのつなぎ方を探していて、このページに来た方もいると思います。できることの一覧はたくさん出てくる。でも、実際にどこでつまずくのかは、使ってみるまで分からない。

私は2026年5月から、Claude Code（AIにパソコン上の作業を任せるツール）からNotionを操作するための連携ツールを自分で作って使っています。中身はNotion APIを呼ぶPythonのプログラムで、ツールの数は60個。9月にはAPIの仕様変更に合わせて3か所を直しました。

その中身をもとに、Notion APIでできることと、2025年以降の仕様変更でつまずくところを順に書いていきます。APIの仕様は、すべて2026年9月28日にNotionの開発者向けドキュメントで確かめた内容。

Notion APIでできることは、ページとデータベースとファイルの読み書き

公式ドキュメントでは、Notion APIで扱えるものとして、ページ、データベース、データソース、ブロック、ユーザー、コメント、ファイルアップロード、検索が挙げられています。リクエストはすべて https://api.notion.com にHTTPSで送り、中身はJSONです。

業務に置き換えると、次のような使い方になります。

使い始めるには、認証の方法を選ぶ

必要なのは、リクエストに付けるトークン。公式ドキュメントのAuthorizationでは、次の3つが案内されています。

以前は「インテグレーション」と呼ばれていたものが、いまのドキュメントでは「コネクション」になっている。古い解説記事と画面の名前が合わないときは、これが理由です。

内部コネクションで一番多いつまずきは、ページの共有を忘れることでしょう。ドキュメントには、内部コネクションがページにアクセスするには、Notionでそのページを開き、メニューの「コネクションを追加」から選ぶ必要があり、共有していないページへのリクエストはエラーになると書かれています。

私のツールは、OAuthの公開コネクションと、内部コネクションのトークンの両方で動く作りです。OAuthにしたのは、ページを1つずつ共有しなくても、許可の画面でまとめて選べるからです。

私がNotion APIで作ったもの。Claude Code用の連携ツール

作ったのは、MCPサーバーと呼ばれる種類のプログラムです。MCPは、AIが外部のツールを呼び出すための共通の約束事。Claude Codeに「このページの表を更新して」と頼むと、Claude Codeが私のツールを呼び、ツールがNotion APIにリクエストを送ります。

Notionにも公式のMCPサーバーはある。Notionがホストしていて、OAuthで認証し、検索やページの読み書き、ページとデータベースの作成ができると公式ドキュメントに書かれています。普段の検索や読み書きなら、まずは公式のほうで足りるはず。

それでも自分で作ったのは、手元のファイルを使う作業とまとめて処理する作業を、自分のやり方で組みたかったから。よく使っている機能を書きます。

ローカルの画像をページのアイコンやカバーにする

パソコンに保存してある画像を、そのままNotionページのアイコンやカバーに設定する機能です。

中でやっているのは、NotionのFile Upload APIの手順どおり。ファイルアップロードを作り、ファイルを送り、できたIDをページのアイコンに指定する、の3段です。

ドキュメントでは、1回で送れるのは20MBまでで、それを超えるファイルは分割して送ります。無料のワークスペースは1ファイル5MiBまで、有料のワークスペースは5GiBまで。私のツールは20MBを境に自動で切り替え、大きいファイルは10MBずつに分けて送っています。

1つ落とし穴があります。アップロードしたファイルは1時間以内にページやブロックに付けないと、自動的に使えない状態になります（出典はUploading small files）。アップロードとページへの設定は、間を空けずに続けて実行するようにしました。

まとめて更新する、重複させずに追加する

何十ページもの同じ項目を書き換える、何件ものレコードを一度に追加する、といった一括処理も入れています。

特に役に立っているのは「あれば更新、なければ追加」の機能です。日付などのキーになる列を決めておき、同じ日付のレコードがすでにあれば数字を上書き、なければ新しく作る。毎日同じ処理を回しても、レコードが二重にならない。広告の日々の数字のように、同じ日付の数字があとから修正される種類のデータを貯めるときに向いています。

既存のページをテンプレートにして、数字を差し込んで作る

もう1つよく使うのが、テンプレートの機能です。既存のページを{{月}} や {{CV}} のような差し込み位置つきで保存しておき、値を渡すと同じ形のページができます。私は広告の月次レポートや進捗報告のページをこれで作っています。見出しと表を毎回手で組み直す手間は、もうない。

Markdownで書いた文章をページにする

AIが書いた文章は、たいていMarkdown（見出しに#、箇条書きに-を使う書き方）で出てきます。これをNotionのブロックに変える変換を、ツールの中に持たせた。対応しているのは、見出し、箇条書き、番号付きリスト、チェックボックス、引用、コード、区切り線、表です。

作り始めて3日後に、長い文章を入れると validation_error で失敗する問題にぶつかりました。

原因はAPIの上限。公式のRequest limitsでは、配列は1回のリクエストで100個まで、ブロックは1000個まで、リクエスト全体は500KBまでと決まっています。ページに追加するブロックも、100個を超えるとまとめて送れない。そこで、最初の100ブロックでページを作り、残りを100個ずつ追記する処理に変えました。

もう1つの方法が、2026-03-11版から使えるMarkdownのエンドポイントです。PATCH /v1/pages/{page_id}/markdown に、ページ全体を置き換える replace_content か、文字列を探して置き換える update_content を送ると、Notion側がMarkdownを解釈してくれます（出典はUpdate page markdown）。

このエンドポイントは、Notion-Version ヘッダーに 2026-03-11 を指定しないと使えません。子ページやデータベースを消してしまう変更は、allow_deleting_content を true にしない限り止めてくれる作りです。置き換えの操作は1回のリクエストで100個まで。

実行前に中身を確認する

書き込み系の機能は、どれも最初は「何をするか」を表示するだけで、実際には書き込まない設定にしました。確認してから、本当に実行する指示を出す。AIに任せる作業だからこそ、間違ったページを消す事故を先に防いでおきたかったからです。

2025年9月の変更で、データベースとデータソースが分かれた

影響が大きいのは、すでにデータベースを操作するコードを持っている人。

公式のアップグレードガイドによると、1つのデータベースが複数のデータソースを持てるようになり、これまで database_id を使っていた操作の多くが data_source_id を使う形に変わっています。主な変更を表にしました。

私のツールも、ここで3か所つまずいた。2026年9月8日に直したときの記録をそのまま書きます。

1つめはデータベースの作成。親の指定に type を付けていなかったため、body.parent.type should be defined という400エラーが返っていました。列の定義も initial_data_source の中に移す必要がありました。

2つめはデータベースへのページ追加です。取得したページの親の欄に出てくるIDは、データベースのIDではなくデータソースのID。これをデータベースのIDとして渡すと、404（見つからない）になります。いまは404が返ったら、データソースのIDとして1回だけ送り直すようにしています。

3つめがMarkdownでの置き換え。送る中身の形が違っていました。type に replace_content を指定し、同じ名前の replace_content というキーの中に本文を入れるのが正しい形。

レコードの検索は、データベースのIDを受け取ったら、まずデータベースを取得して最初のデータソースのIDを調べ、それを覚えておいて使う作りです。利用者はいままでどおりデータベースのURLを渡せば動きます。

2026-03-11版で名前が変わったもの

Notion APIは、リクエストのヘッダーに Notion-Version を付けて、どの版の仕様で動かすかを指定します。Versioningによると、2026年9月28日時点の最新は2026-03-11版で、後方互換性のない変更を入れるときに新しい版が出ます。

2026-03-11版での変更は3つです（出典はUpgrade guide 2026-03-11）。

• ブロックの追加位置を指定する after が、position というオブジェクトに変わった
• ゴミ箱を表す archived が、in_trash という名前に変わった
• 会議メモのブロックの種類が transcription から meeting_notes に変わった

ガイドには、ほとんどのコネクションは簡単な検索と置換で対応できると書かれています。私のツールでも、対応の中心は名前の置き換えと、after を position に変える処理でした。ただ、古い版の返り値を前提にしたコードが残っていると気づきにくいので、返り値は in_trash と archived の両方を見るようにしてあります。

レート制限は1分あたり180回か600回。429の扱いを先に決める

180回と600回。2026年9月28日時点のRequest limitsに載っている、コネクションごとの1分あたりの上限です。

これとは別に、ワークスペース全体で共有する上限もあり、コネクションごとの上限に収まっていても止められることがあるとされています。

上限を超えると、HTTP 429と rate_limited のエラーが返ります。ドキュメントの指示は、429と529のときは Retry-After ヘッダーの秒数を守って再試行し、待ち時間を少しずつ延ばすこと。すべてのエラーを再試行してはいけない、とも書かれています。

白状すると、ここはまだ甘い。

並列で送るときは同時に3本までに抑えていますが、429が返ったときに自動で待って再試行する処理は入っていません。数百件をまとめて入れる使い方を始める前に足すつもりです。これから作る方は、最初から入れておくほうが楽。

文字数の上限もあります。リッチテキスト（段落の中の文字）は1つあたり2000字まで、URLも2000字まで。長い文章を1つの段落にまとめて送ると、ここで止まります。

ZapierやMakeで使うなら、プログラムを書かなくていい

ここまでプログラムを書く前提で説明してきましたが、ノーコードの自動化ツールでもNotion APIは使えます。Zapierや、以前Integromatと呼ばれていたMake（2022年に名前が変わりました）には、Notionとつなぐ機能があります。

フォームの回答をデータベースに1件ずつ追加する、新しいレコードができたらSlackに通知する。こうした1対1の連携なら、ノーコードのほうが早く作れて、直すのも楽です。

自分でコードを書くほうが向いているのは、次のような場面です。

• 手元のファイルを扱う（画像のアップロード、CSVからの一括登録）
• 何百件もまとめて処理し、途中で失敗したところから再開したい
• 「あれば更新、なければ追加」のように、既存のデータと突き合わせる

最初の一歩。自分の作業をどれか自動化してみる

Notion APIの使い道を一覧で眺めても、自分の業務にどう当てはまるかは見えにくいものです。

おすすめは、毎週手で繰り返している作業を1つだけ選ぶこと。私の場合、それが広告のレポートのページづくりでした。同じ見出しと表を毎月作っていたものを、テンプレートに数字を差し込む形に変えた。広告の数字を社内で共有する話は広告運用の内製化にも書きました。

• 自動化したい作業は、毎週同じ手順で繰り返しているか
• 使うトークンの種類を決めたか（自分用なら個人用アクセストークン）
• 内部コネクションなら、対象のページにコネクションを追加したか
• データベースを扱うなら、データソースのIDを使う形になっているか
• 429が返ったときに待って再試行する処理を入れたか

APIをつないで計測や通知を自動化する考え方は、広告の分野でも変わらない。Metaのコンバージョン APIをサーバーから送る話はMetaのコンバージョンAPI（CAPI）で、自社LPに入れたときの手順ごと書いています。