openhands/notion

Notion

<IMPORTANT> If authenticated Notion MCP tools are available in the environment, use them first. MCP tools do not require passing `NOTION_INTEGRATION_KEY` as a tool argument; authentication is handled by the configured MCP integration.

Use the direct Notion REST API examples below only when MCP is unavailable or when you explicitly need raw API/curl access. For that direct-API path, first check whether the required environment variable is set:

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

If it’s missing and you need the direct API path, ask the user to provide it (or connect a Notion integration) before proceeding:

• NOTION_INTEGRATION_KEY: Notion integration secret (starts with ntn_...)

Whether you use MCP or the direct API, also confirm the configured integration has been shared with the target page/database in Notion. </IMPORTANT>

Base headers for direct API calls

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

Find a page (search)

Use Notion’s search endpoint to find a page by title.

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 .

Create a page under a parent page

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 .

Append blocks to an existing page

Use the page’s block id (same as page id) to append children.

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 .

Tips / gotchas

• Sharing is required: even with a valid key, the integration can’t see a page/database until it has been shared with the integration in the Notion UI.
• Rate limits: keep requests small; for large pages, create the page first and then append blocks in batches.
• IDs format: Notion IDs may be returned with dashes; both dashed and non-dashed forms typically work in API calls.

Documentation

• Notion API: https://developers.notion.com/reference/intro
• Search: https://developers.notion.com/reference/post-search
• Create a page: https://developers.notion.com/reference/post-page
• Append block children: https://developers.notion.com/reference/patch-block-children