MH notion

Notion API for creating and managing pages, databases, and blocks.

Security Scan

The skill's requested access and runtime instructions match its Notion integration purpose; only a small mismatch between the declared env var and the examples in SKILL.md is worth noting.

Purpose & Capability

Name/description (Notion API page/database/block management) align with the single requested credential (NOTION_API_KEY) and the curl-based API examples. Required actions (create integration, share pages) are consistent with Notion integrations.

Instruction Scope

SKILL.md stays within the Notion API domain and only references the user's Notion integration and a local config file (~/.config/notion/api_key). However, the examples set NOTION_KEY by reading ~/.config/notion/api_key rather than demonstrating use of the declared env var NOTION_API_KEY — a minor inconsistency in how credentials are expected to be provided.

Install Mechanism

Instruction-only skill with no install steps and no code files, so nothing is written to disk or fetched during installation.

Credentials

Only one credential is required (NOTION_API_KEY), which is appropriate. The SKILL.md shows storing the key in ~/.config/notion/api_key and sourcing it into NOTION_KEY; the registry metadata declares NOTION_API_KEY as the primaryEnv — the mismatch should be clarified but is not disproportionate.

Persistence & Privilege

always is false and there are no install hooks or requests to modify other skill or system-wide configs. Default autonomous invocation is allowed (platform default) but not combined with other concerning privileges.

Assessment

This skill appears to do exactly what it says: call the Notion API using your Notion integration key. Before installing, consider: (1) Prefer providing the key via the platform's declared NOTION_API_KEY env variable or confirm whether the agent will read ~/.config/notion/api_key (the SKILL.md examples use the file); (2) Use a dedicated, least-privilege Notion integration token that you can revoke; (3) Avoid placing the key in a world-readable file — restrict file permissions if you follow the SKILL.md example; (4) Confirm the agent will only send requests to api.notion.com and that you’re comfortable with the agent having that single API key access.

notion

Use the Notion API to create/read/update pages, data sources (databases), and blocks.

Setup

1. Create an integration at https://notion.so/my-integrations
2. Copy the API key (starts with ntn_ or secret_)
3. Store it:

mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key

4. Share target pages/databases with your integration (click "..." → "Connect to" → your integration name)

API Basics

All requests need:

NOTION_KEY=$(cat ~/.config/notion/api_key)
curl -X GET "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

Note: The Notion-Version header is required. This skill uses 2025-09-03 (latest). In this version, databases are called "data sources" in the API.

Common Operations

Search for pages and data sources:

curl -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "page title"}'

Get page:

curl "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03"

Get page content (blocks):

curl "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03"

Create page in a data source:

curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "xxx"},
    "properties": {
      "Name": {"title": [{"text": {"content": "New Item"}}]},
      "Status": {"select": {"name": "Todo"}}
    }
  }'

Query a data source (database):

curl -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Active"}},
    "sorts": [{"property": "Date", "direction": "descending"}]
  }'

Create a data source (database):

curl -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "title": [{"text": {"content": "My Database"}}],
    "properties": {
      "Name": {"title": {}},
      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
      "Date": {"date": {}}
    }
  }'

Update page properties:

curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'

Add blocks to page:

curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello"}}]}}
    ]
  }'

Property Types

Common property formats for database items:

• Title: {"title": [{"text": {"content": "..."}}]}
• Rich text: {"rich_text": [{"text": {"content": "..."}}]}
• Select: {"select": {"name": "Option"}}
• Multi-select: {"multi_select": [{"name": "A"}, {"name": "B"}]}
• Date: {"date": {"start": "2024-01-15", "end": "2024-01-16"}}
• Checkbox: {"checkbox": true}
• Number: {"number": 42}
• URL: {"url": "https://..."}
• Email: {"email": "[e-mail]"}
• Relation: {"relation": [{"id": "page_id"}]}

Key Differences in 2025-09-03

• Databases → Data Sources: Use /data_sources/ endpoints for queries and retrieval
• Two IDs: Each database now has both a database_id and a data_source_id
  • Use database_id when creating pages (parent: {"database_id": "..."})
  • Use data_source_id when querying (POST /v1/data_sources/{id}/query)
• Search results: Databases return as "object": "data_source" with their data_source_id
• Parent in responses: Pages show parent.data_source_id alongside parent.database_id
• Finding the data_source_id: Search for the database, or call GET /v1/data_sources/{data_source_id}

Notes

• Page/database IDs are UUIDs (with or without dashes)
• The API cannot set database view filters — that's UI-only
• Rate limit: ~3 requests/second average
• Use is_inline: true when creating data sources to embed them in pages