notion

Notion

Notion REST の curl、環境変数、JSON 本文の定型スニペットに対応する Windows PowerShell の例は、references/windows.md にあります。

環境内で認証済みの Notion MCP ツールを利用できる場合は、まずそれを使用してください。MCP ツールでは、ツール引数として `NOTION_INTEGRATION_KEY` を渡す必要はありません。認証は設定済みの MCP インテグレーションによって処理されます。

以下の直接 Notion REST API の例は、MCP を利用できない場合、または生の API／curl へのアクセスが明示的に必要な場合にのみ使用してください。直接 API を使用する場合は、まず必要な環境変数が設定されているか確認してください。

[ -n "$NOTION_INTEGRATION_KEY" ] && echo "NOTION_INTEGRATION_KEY is set" || echo "NOTION_INTEGRATION_KEY is NOT set"

環境変数が設定されておらず、直接 API を使用する必要がある場合は、先にユーザーに値の提供（または Notion インテグレーションの接続）を依頼してください。

• NOTION_INTEGRATION_KEY：Notion インテグレーションのシークレット（ntn_... で始まります）

MCP と直接 API のどちらを使用する場合も、設定済みのインテグレーションが Notion の対象ページ／データベースと共有されていることも確認してください。

直接 API 呼び出しの基本ヘッダー

-H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
-H "Notion-Version: 2022-06-28" \
-H "Content-Type: application/json"

ページを検索する

Notion の検索エンドポイントを使用して、タイトルからページを検索します。

curl -s https://api.notion.com/v1/search \
  -H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "OpenHands Wiki",
    "page_size": 10
  }' | jq .

親ページの下にページを作成する

PARENT_PAGE_ID="<parent_page_id>"

curl -s https://api.notion.com/v1/pages \
  -H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"type": "page_id", "page_id": "'"${PARENT_PAGE_ID}"'"},
    "properties": {
      "title": {
        "title": [{"type": "text", "text": {"content": "My new page"}}]
      }
    },
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Hello from OpenHands."}}]
        }
      }
    ]
  }' | jq .

既存のページにブロックを追加する

ページのブロック ID（ページ ID と同じ）を使用して、子ブロックを追加します。

PAGE_ID="<page_id>"

curl -s -X PATCH "https://api.notion.com/v1/blocks/${PAGE_ID}/children" \
  -H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {"rich_text": [{"type": "text", "text": {"content": "Appended section"}}]}
      }
    ]
  }' | jq .

ヒント／注意点

• 共有が必要です：有効なキーがあっても、Notion の UI でインテグレーションとページ／データベースを共有するまでは、そのページ／データベースをインテグレーションから参照できません。
• レート制限：リクエストは小さく保ってください。大きなページの場合は、まずページを作成し、その後、ブロックを複数回に分けて追加してください。
• ID の形式：Notion の ID はハイフン付きで返されることがあります。通常は、API 呼び出しでハイフン付きとハイフンなしのどちらも使用できます。

ドキュメント

• Notion API：https://developers.notion.com/reference/intro
• 検索：https://developers.notion.com/reference/post-search
• ページの作成：https://developers.notion.com/reference/post-page
• ブロックの子要素の追加：https://developers.notion.com/reference/patch-block-children