Notion API スキル

このスキルにより、Notion REST API を通じて Notion ワークスペースと対話することができます。直接的な REST 呼び出しには curl と jq を使用するか、タスクに応じて適切なアドホックスクリプトを記述してください。

認証

API キーの処理

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

重要: NOTION_API_TOKEN を Authorization ヘッダー以外のどこにも表示、ログ、送信しないでください。その存在を確認し、不足している場合は要求し、リクエストで使用してください。ただし、エコーまたは公開しないでください。

リクエストヘッダー

すべてのリクエストには、これらのヘッダーが必要です:

-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 を使用

レート制限

• 平均: インテグレーションごとに 1 秒あたり 3 リクエスト
• バースト: この制限を超える短いバーストは許可されます
• レート制限レスポンス: Retry-After ヘッダー付きの HTTP 429
• 戦略: 429 レスポンスを受け取ったときに指数バックオフを実装

リクエストサイズ制限

タイプ	制限
ペイロードあたりの最大ブロック要素	1000
最大ペイロードサイズ	500KB
リッチテキストコンテンツ	2000 文字
URL	2000 文字
数式	1000 文字
メールアドレス	200 文字
電話番号	200 文字
複数選択オプション	100 項目
リレーション	100 関連ページ
ユーザーメンション	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

リクエストあたり最大 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

ボットユーザー (自己) の取得

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

ページレベルのコメントについては、block_id としてページ 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 - リッチテキストオブジェクトの構造と注釈