notion-api

Notion の中身をエージェントに読み書きさせたいときに効きます。MCP のサーバーや専用の CLI を入れず、curl と jq で Notion の REST API を直接呼ぶ書き方をまとめた手引きです。

その場で使い捨てのスクリプトを書かせてもよい、とされています。curl の命令の例が 23 個並んでいるので、エージェントが API の文書を探しに行かずに済みます。

SKILL.md（2026-10-23 時点）

14,675 バイト

同梱の参照（ブロック・プロパティ・絞り込み・リッチテキスト）

4 件

1 秒あたりの平均の上限

3 回

使う API の版

2025-09-03

できること

• 探すPOST /v1/search。ページかデータソースに絞れる
• ページ取得・作成・更新・アーカイブ、25 件を超える参照のプロパティの取得
• ブロック（本文）子の取得・追記・更新・削除。追記は先頭や特定のブロックの後ろにも
• データベース取得・絞り込みと並べ替えの問い合わせ・作成・更新
• データソースデータベースの中の表を作る
• ユーザーとコメントユーザーの一覧、コメントの取得と作成、議論への返信

ページを取得しても返るのはプロパティで、本文ではありません。本文はページの ID を block_id にして「子のブロックの取得」で読む、と注意書きがあります。

同梱の参照が厚い

同梱の 4 本は、JSON の形を種類ごとに並べた早見表です。ブロックの参照は 28 の小見出しで種類を並べ、コードのブロックで使える言語名まで載せています。

プロパティの参照は列の型を 21 種並べ、ページに値を書く形も 1 つずつ示しています。絞り込みの参照は、型ごとの条件と AND・OR の組み方、問い合わせの例をまとめています。

一覧を最後まで取る手順

一覧の API は has_more と next_cursor を返します。has_more が false になるまで、next_cursor を start_cursor に入れて繰り返す、と手順が書かれています。

鍵をエージェントに扱わせたくないとき

このスキルは、API の鍵を環境変数か会話から受け取り、エージェントが自分でヘッダーに入れる作りです。鍵を会話に貼るのを避けたいなら、先に環境変数 NOTION_API_TOKEN を用意しておくか、鍵を扱わない別の手段を選んでください。

大量のページを一気に書き換えるとき

平均で 1 秒 3 回までの上限があり、1 回に送れるブロックは 100 個までです。何千ページもの移行には、待ちと再送を組み込んだスクリプトを別に用意するほうが向いています。

手元のノートを扱いたいとき

手元の Markdown のノートなら、Obsidian の CLI を使う obsidian-cli の側です。文書を一緒に書き進めたいなら doc-coauthoring があります。

解析で読み取れること

本文は curl で https://api.notion.com に要求を送る前提です。シェルでの命令の実行と、Notion のページ・ブロック・データベースの書き換えや削除の書き方を含みます。

allowed-tools の指定はありません。同梱は参照の Markdown 4 本だけで、スクリプトはありません。

書き換えと削除の前に確かめる決まり

ブロックの削除はごみ箱に移すだけで、戻せる、と書かれています。ページの「削除」も archived: true にする形です。

ブロックの更新は、指定した欄の値を丸ごと置き換えます。ファイルのプロパティを更新すると、既存のファイルはすべて置き換わる、と参照にあります。

鍵を表に出さない

NOTION_API_TOKEN は Authorization のヘッダー以外に表示・記録・送信するな、と強く書かれています。あるかどうかを確かめ、無ければ聞き、要求に使うだけにせよ、という決まりです。

ただし同梱の参照のうち 2 本は、命令の例で $NOTION_API_KEY という別の名前を使っています（2026-10-23 時点）。写して使うときは、名前を NOTION_API_TOKEN にそろえてください。

見つからない誤りは、共有の漏れのことが多い

誤りの表では、404 の object_not_found を「存在しないか、インテグレーションに共有されていない」と説明しています。Notion の鍵は、共有したページにしか届きません。

429 の rate_limited は Retry-After を見て、間隔を広げながら再送せよ、とされています。

本文の一部は、指定の版では古い書き方

同じ版では、データベースの取得はデータソースの一覧を返す形に変わり、列の定義（プロパティ）はデータソースの取得の側に移った、と公式の移行の手引きにあります。本文は、データベースの取得が「データソースとプロパティを含む構造」を返すと書いています。

本文の命令が思った結果を返さないときは、公式の文書の新しい形を確かめてください。データベースの作成は initial_data_source を使う新しい形で書かれています。

API でできないこと

コメントは、新しいインラインの議論を始めることも、既存のコメントを直すことも消すこともできない、と書かれています。状態（status）のプロパティを API で新しく作ることもできません。

同期ブロックの中身の更新、表の列数の後からの変更も、参照ではできないとされています。

ライセンスの書き方が 2 通り

リポジトリの LICENSE.txt は CC0 1.0 で、プラグインの定義（plugin.json）には MIT と書かれています（2026-10-23 確認）。

鍵はどこで手に入れますか

本文は、環境変数 NOTION_API_TOKEN、会話で渡された鍵の順に探し、どちらも無ければ利用者に聞け、としています。鍵の作り方は書かれていないので、Notion の側でインテグレーションを作り、読ませたいページを共有しておく必要があります。

認証が通っているかを確かめるには

GET /v1/users/me でボットのユーザーを取ってみる、という確かめ方が書かれています。鍵が正しければ、そのインテグレーションの情報が返ります。

1 回でどのくらい書き込めますか

本文の表では、1 回の要求の大きさは 500KB まで、ブロックの配列は 100 個まで、リッチテキストは 1 つ 2,000 文字までです。ブロックの入れ子は 1 回の追記で 2 段までとされています。

Codex でも使えますか

公開元の README が示す入れ方は、skills の CLI と Claude Code（と Cowork）のプラグインです。Codex の名前は挙がっていないので、当サイトでは対応のエージェントを Claude Code だけにしています。