Notion

---
name: notion
description: Create, search, and update Notion pages/databases using the Notion API. Use for documenting work, generating runbooks, and automating knowledge base updates.
triggers:
- 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:

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