notion-enhanced-markdown-integration

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

Security Scan

The skill's stated purpose (Notion API integration) matches the operations shown, but the instructions and declared requirements are inconsistent about how the Notion credential is provided and where it is stored, and the skill references a secret file path that wasn't declared — this mismatch deserves caution before installing.

Purpose & Capability

The name/description and the SKILL.md consistently implement Notion API operations (pages, databases/data_sources, blocks, markdown). Requiring a Notion API credential is proportionate. However, the registry metadata declares NOTION_API_KEY as the required env var, while the SKILL.md examples use a file (~/.config/notion/api_key) and an environment variable named NOTION_KEY — an inconsistency between claimed and actual usage.

Instruction Scope

The instructions tell the agent/operator to read the API key from ~/.config/notion/api_key (via cat) and set NOTION_KEY, but the skill's declared requirements do not list that config path. The SKILL.md otherwise confines actions to api.notion.com endpoints and curl calls (expected), but the explicit filesystem access to a user key file is not declared and expands the surface area.

Install Mechanism

This is an instruction-only skill with no install spec and no code files. That minimizes install-time risk — nothing is downloaded or written by an installer.

Credentials

Only a single credential (Notion API key) is requested, which is appropriate. But there's inconsistency: registry expects NOTION_API_KEY as primaryEnv, while SKILL.md uses a file and an env var named NOTION_KEY. The skill does not declare the ~/.config/notion/api_key path even though the instructions read it. That mismatch weakens the stated proportionality and could lead to unexpected secret handling.

Persistence & Privilege

always is false and the skill does not request system-wide modifications or persistent presence. Autonomous invocation is allowed (platform default) but not combined with other high-risk flags here.

What to consider before installing

This skill appears to do what it says (curl calls to api.notion.com to read/write pages and markdown), but the SKILL.md and registry metadata disagree about how the Notion key is provided: the registry lists NOTION_API_KEY, while the instructions tell you to store the key in ~/.config/notion/api_key and use NOTION_KEY. Before installing, ask the author to clarify/fix: (1) which environment variable name the platform should provide (NOTION_API_KEY vs NOTION_KEY), (2) whether the skill will read ~/.config/notion/api_key — if so, that path should be declared and you should be aware of file permissions (avoid world-readable files), and (3) confirm the skill only contacts api.notion.com. If you proceed, grant the integration the minimum Notion scopes needed (read-only vs insert_content) and avoid storing long-lived keys in unsecured files. If you want higher assurance, request the full (non-truncated) SKILL.md and an explanation of secret-handling behavior so the inconsistencies can be resolved.

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: 2026-03-11" \
  -H "Content-Type: application/json"

Note: The Notion-Version header is required. This skill uses 2026-03-11 (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: 2026-03-11" \
  -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: 2026-03-11"

Get page content (blocks):

For simple content access, prefer the Markdown API (GET /v1/pages/{page_id}/markdown). Use the blocks API only when you need low-level block data or unsupported block types.

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

Create page in a data source:

curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2026-03-11" \
  -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: 2026-03-11" \
  -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: 2026-03-11" \
  -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: 2026-03-11" \
  -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: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello"}}]}}
    ]
  }'

Markdown Page Operations

Use the Markdown API to read and write page content as plain Markdown — no need to construct block JSON.

Create page with markdown:

curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "markdown": "# Meeting Notes\n\nContent here.\n\n- item 1\n- item 2"
  }'

Constraints:

• markdown and children are mutually exclusive in the same request
• If properties.title is omitted, the first # h1 heading becomes the page title
• Requires insert_content capability on the parent
• Only works for pages under a parent page (not a database)

Read page as markdown:

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

Response: { "object": "page_markdown", "id": "...", "markdown": "...", "truncated": false, "unknown_block_ids": [] }

• Add ?include_transcript=true to include meeting transcripts
• If truncated: true, fetch remaining blocks using the IDs in unknown_block_ids

Update page markdown:

# Search-and-replace (recommended)
curl -X PATCH "https://api.notion.com/v1/pages/{page_id}/markdown" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "command": {
      "type": "update_content",
      "old_str": "old text",
      "new_str": "new text"
    }
  }'

# Full replacement
curl -X PATCH "https://api.notion.com/v1/pages/{page_id}/markdown" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "command": {
      "type": "replace_content",
      "new_str": "# New Title\n\nReplaced content."
    }
  }'

Two command types:

• update_content — search-and-replace (old_str → new_str); fails with validation_error if old_str appears multiple times (add "replace_all_matches": true to override)
• replace_content — replaces all page content with new_str

Both commands return the full updated page markdown. Constraints:

• Matching is case-sensitive
• Operations that would delete child pages/databases are rejected unless "allow_deleting_content": true is set
• Synced pages cannot be updated

Supported Block Types (Markdown)

Block Type	Markdown Syntax
Paragraph	plain text
Heading 1–4	# through ####
Bulleted list item	- item
Numbered list item	1. item
To-do	- [ ] / - [x]
Toggle	<details><summary>…</summary>…</details>
Quote	> quote
Callout	<callout>…</callout>
Divider	---
Code block	```language … ```
Equation	$$ equation $$
Table	<table><tr><td>…</td></tr></table>
Image	
File / Video / Audio / PDF	<file src="url">caption</file>
Child page	<page url="…">title</page>
Columns	<columns><column>…</column></columns>

Unsupported block types render as <unknown url="..." alt="block_type"/> placeholder tags.

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 2026-03-11

• 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, with 429 rate_limited responses using Retry-After
• Append block children: up to 100 children per request, up to two levels of nesting in a single append request
• Payload size limits: up to 1000 block elements and 500KB overall
• Use is_inline: true when creating data sources to embed them in pages
• markdown field in create/update is mutually exclusive with children
• Markdown pages exceeding ~20,000 blocks will have truncated: true; fetch remaining content using block IDs in unknown_block_ids
• All string matching in update_content is case-sensitive
• In-page \n must be actual newlines in JSON; use single quotes in cURL