notion
Create, search, and update Notion pages/databases using the Notion API. Use for documenting work, generating runbooks, and automating knowledge base updates.
How do I install this agent skill?
npx skills add https://github.com/openhands/extensions --skill notionIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill enables interaction with the Notion API using standard tools like curl and PowerShell. It follows security best practices for credential management by using environment variables. However, it presents a surface for indirect prompt injection by processing external content from Notion.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
2/2 files flagged
What does this agent skill do?
Notion
Windows PowerShell equivalents for the repeated Notion REST curl, environment-variable, and JSON-body snippets are in references/windows.md.
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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/openhands/extensions/notion">View notion on skillZs</a>