notion-api

Notion API スキル

このスキルを使うと、Notion REST API を通じて Notion ワークスペースを操作できます。直接 REST API を呼び出すには curl と jq を使うか、タスクに応じてその場でスクリプトを作成してください。

認証

API キーの取り扱い

1. 環境変数：環境内で NOTION_API_TOKEN を利用できるか確認します
2. ユーザー提供のキー：ユーザーがコンテキスト内で API キーを提供した場合は、代わりにそれを使用します
3. 利用可能なキーがない場合：どちらも利用できない場合は、AskUserQuestion（または同等の機能）を使用して、ユーザーに API キーを要求します

重要：Authorization ヘッダー以外の場所で NOTION_API_TOKEN を表示、ログ出力、送信しないでください。存在を確認し、見つからない場合はユーザーに尋ね、リクエストで使用します。ただし、値をそのまま出力したり、漏えいさせたりしてはいけません。

リクエストヘッダー

すべてのリクエストで、次のヘッダーが必要です。

-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json"

認証の確認

ボットユーザーを取得して API キーをテストします。

curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

ベース URL と規則

• ベース URL：https://api.notion.com
• API バージョン：2025-09-03（必須ヘッダー）
• データ形式：すべてのリクエスト／レスポンス本文で JSON を使用します
• ID：UUIDv4 形式（リクエストではハイフンを省略できます）
• タイムスタンプ：ISO 8601 形式（2020-08-12T02:12:33.231Z）
• プロパティ名：snake_case
• 空の値：空文字列ではなく null を使用します

レート制限

• 平均：インテグレーションごとに毎秒 3 リクエスト
• バースト：この制限を一時的に超えるリクエストは許可されます
• レート制限時のレスポンス：Retry-After ヘッダーを含む HTTP 429
• 対策：429 レスポンスを受け取った場合は、指数バックオフを実装します

リクエストサイズの制限

種類	上限
ペイロードあたりのブロック要素の最大数	1000
ペイロードの最大サイズ	500KB
リッチテキストの内容	2000 文字
URL	2000 文字
数式	1000 文字
メールアドレス	200 文字
電話番号	200 文字
マルチセレクトのオプション	100 項目
リレーション	関連ページ 100 件
People メンション	ユーザー 100 人
リクエストあたりのブロック配列	100 要素

破壊的操作の確認

重要：データを変更または削除する操作を実行する前に、必ずユーザーに確認してください。以下が含まれます。

• ページまたはブロックの更新
• ページまたはブロックの削除／アーカイブ
• データベーススキーマの変更
• ページの作成（複数または一括の場合）
• 一括操作全般

関連する操作を論理的にまとめた場合は、確認は 1 回で十分です。

コア API エンドポイント

検索

アクセス可能なすべてのページとデータベースを検索します。

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "search term",
    "filter": {"property": "object", "value": "page"},
    "sort": {"direction": "descending", "timestamp": "last_edited_time"},
    "page_size": 100
  }' | jq

フィルター値："page" または "data_source"（省略すると両方が対象になります）

ページ

ページの取得

curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

注：この操作で返されるのはページのプロパティであり、コンテンツではありません。コンテンツを取得するには、ページ ID を指定して「ブロックの子要素を取得」を使用します。

ページの作成

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "properties": {
      "title": {
        "title": [{"text": {"content": "Page Title"}}]
      }
    },
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Paragraph content"}}]
        }
      }
    ]
  }' | jq

親の指定方法：

• {"page_id": "..."} - ページの下に作成します
• {"database_id": "..."} - データベース内に作成します（従来方式）
• {"data_source_id": "..."} - データソース内に作成します（API v2025-09-03 以降）

ページの更新

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "title": {"title": [{"text": {"content": "Updated Title"}}]}
    },
    "icon": {"type": "emoji", "emoji": "📝"},
    "archived": false
  }' | jq

追加の更新オプション：cover、is_locked、in_trash

ページのアーカイブ（削除）

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}' | jq

ページプロパティ項目の取得

参照が 25 件を超えるプロパティの場合：

curl -s "https://api.notion.com/v1/pages/{page_id}/properties/{property_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

ブロック（ページコンテンツ）

ブロックの子要素を取得

curl -s "https://api.notion.com/v1/blocks/{block_id}/children?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

ページコンテンツを取得するには、ページ ID を block_id として指定します。各ブロックの has_children を確認して、入れ子になったコンテンツを取得してください。

ブロックの子要素を追加

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}/children" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {
          "rich_text": [{"type": "text", "text": {"content": "New Section"}}]
        }
      },
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Content here"}}]
        }
      }
    ]
  }' | jq

1 回のリクエストで追加できるブロックは最大 100 個、入れ子は最大 2 階層です。

リクエスト本文で指定できる位置：

• デフォルト：末尾に追加します
• "position": {"type": "start"} - 先頭に挿入します
• "position": {"type": "after_block", "after_block": {"id": "block-id"}} - 指定したブロックの後に挿入します

ブロックの取得

curl -s "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

ブロックの更新

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "paragraph": {
      "rich_text": [{"type": "text", "text": {"content": "Updated content"}}]
    }
  }' | jq

更新すると、指定したフィールドの値全体が置き換えられます。

ブロックの削除

curl -s -X DELETE "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

ブロックをゴミ箱に移動します（復元できます）。

データベース

データベースの取得

curl -s "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

データソースとプロパティを含むデータベースの構造を返します。

データベースをクエリする

curl -s -X POST "https://api.notion.com/v1/databases/{database_id}/query" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "Status",
      "select": {"equals": "Done"}
    },
    "sorts": [
      {"property": "Created", "direction": "descending"}
    ],
    "page_size": 100
  }' | jq

フィルターとソートに関する包括的なドキュメントは、references/filters-and-sorts.md を参照してください。

データベースを作成する

curl -s -X POST "https://api.notion.com/v1/databases" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "title": [{"type": "text", "text": {"content": "My Database"}}],
    "is_inline": true,
    "initial_data_source": {
      "properties": {
        "Name": {"title": {}},
        "Status": {
          "select": {
            "options": [
              {"name": "To Do", "color": "red"},
              {"name": "In Progress", "color": "yellow"},
              {"name": "Done", "color": "green"}
            ]
          }
        },
        "Due Date": {"date": {}}
      }
    }
  }' | jq

データベースを更新する

curl -s -X PATCH "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "title": [{"text": {"content": "Updated Title"}}],
    "description": [{"text": {"content": "Database description"}}]
  }' | jq

データソース（API v2025-09-03+）

データソースは、データベース内の個々のテーブルです。API バージョン 2025-09-03 以降、データベースには複数のデータソースを含めることができます。

データソースを作成する

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"type": "database_id", "database_id": "database-id"},
    "title": [{"type": "text", "text": {"content": "New Data Source"}}],
    "properties": {
      "Name": {"title": {}},
      "Description": {"rich_text": {}}
    }
  }' | jq

ユーザー

すべてのユーザーを一覧表示する

curl -s "https://api.notion.com/v1/users?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

ユーザーを取得する

curl -s "https://api.notion.com/v1/users/{user_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Bot ユーザーを取得する（自分自身）

curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

コメント

コメントを取得する

curl -s "https://api.notion.com/v1/comments?block_id={block_id}&page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

ページレベルのコメントには、ページ ID を block_id として使用してください。

コメントを作成する

ページ上に作成する場合：

curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "page-id"},
    "rich_text": [{"type": "text", "text": {"content": "Comment content"}}]
  }' | jq

ディスカッションに返信する場合：

curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "discussion_id": "discussion-id",
    "rich_text": [{"type": "text", "text": {"content": "Reply content"}}]
  }' | jq

注：API では、新しいインラインディスカッションスレッドの開始や、既存のコメントの編集・削除はできません。

ページネーション

ページネーション対応のエンドポイントは、次の値を返します：

• has_more：結果がさらに存在するかどうかを示すブール値
• next_cursor：次のページのカーソル
• results：項目の配列

すべての結果を取得するには：

1. 最初のリクエストを送信します（start_cursor は省略します）
2. レスポンスの has_more を確認します
3. true の場合は、next_cursor を取得して、次のリクエストの start_cursor に指定します
4. has_more が false になるまで繰り返します

カーソルを使用したリクエストの例：

{
  "page_size": 100,
  "start_cursor": "v1%7C..."
}

エラー処理

HTTP ステータス	コード	説明
400	invalid_json	リクエスト本文が有効な JSON ではありません
400	invalid_request_url	URL の形式が正しくありません
400	invalid_request	リクエストはサポートされていません
400	validation_error	リクエスト本文が想定されるスキーマと一致しません
400	missing_version	Notion-Version ヘッダーがありません
401	unauthorized	ベアラートークンが無効です
403	restricted_resource	トークンに必要な権限がありません
404	object_not_found	リソースが存在しないか、インテグレーションと共有されていません
409	conflict_error	トランザクション中にデータの競合が発生しました
429	rate_limited	レート制限を超過しました（Retry-After ヘッダーを確認してください）
500	internal_server_error	予期しないサーバーエラーです
503	service_unavailable	Notion が利用できないか、60 秒のタイムアウトを超過しました
503	database_connection_unavailable	データベースが応答していません
504	gateway_timeout	リクエストがタイムアウトしました

ベストプラクティス

1. ID を保存する：ページやデータベースを作成したら、後で更新できるように返された ID を保存します
2. プロパティ ID を使用する：安定性を高めるため、プロパティは名前ではなく ID で指定します
3. 操作をまとめる：複数の小さな操作をまとめて、リクエスト数を減らします
4. レート制限を守る：429 レスポンスに対して指数バックオフを実装します
5. has_more を確認する：一覧表示エンドポイントでは、必ずページネーションを処理します
6. 更新前に検証する：更新を行う前に、現在の状態を取得します
7. 環境変数を使用する：API キーをハードコードしないでください
8. エラーを適切に処理する：レスポンスのステータスコードとエラーメッセージを確認します
9. スキーマサイズ：最適なパフォーマンスを得るため、データベーススキーマは 50KB 未満に保ちます
10. プロパティの制限：ページ参照が 25 件を超えるプロパティは、個別に取得する必要があります

参考資料

各トピックの詳細なドキュメントについては、以下を参照してください：

• references/block-types.md - サポートされているすべてのブロックタイプとその構造
• references/property-types.md - データベースのプロパティタイプと値の形式
• references/filters-and-sorts.md - データベースクエリのフィルターとソートの構文
• references/rich-text.md - リッチテキストオブジェクトの構造と注釈