---
id: OpenHands/extensions/notion
version: "29db2a2d"
license: MIT
install: manual
updated: 2026-07-27
---

# notion — This skill provides REST API access to create, search, and update Notion pages and databases. It supports direct API calls with proper authentication headers and includes guidance on MCP tool availability, environment setup, and sharing requirements for integrations.

Publisher: OpenHands · Stars: 130 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/OpenHands/extensions`

## SKILL.md

# Notion

Windows PowerShell equivalents for the repeated Notion REST `curl`, environment-variable, and JSON-body snippets are in `references/windows.md`.

<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:

```bash
[ -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

```bash
-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.

```bash
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

```bash
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.

```bash
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


[View on SkillFed](https://skillfed.io/OpenHands/extensions/notion) · [View on GitHub](https://github.com/OpenHands/extensions)