OpenParable
Skip to content
← Back to skills

Notion Hub

Apps & Automation
notion-hub

Notion Hub is an Agent Skill for apps & automation published in the OpenMinis/MinisSkills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Read and write Notion data using Python + notion-client SDK. Authenticated via NOTION_API_KEY env var. Supports search, page CRUD (Markdown↔Blocks bidirectional conversion), database schema/query/create/add-row, block-level operations (append/update/delete), and comments. Trigger this skill whenever the user mentions "Notion", "notion", "notion-hub", "Notion page", "Notion database", "read Notion", "write Notion", "Notion API", or any scenario requiring programmatic read/write access to Notion data.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/OpenMinis/MinisSkills/blob/HEAD/notion-hub/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/notion-hub, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Notion Hub

Read/write Notion via notion-client Python SDK. All operations through a single CLI script.

Prerequisites

  • Environment variable: NOTION_API_KEY — Notion Internal Integration Token
  • uv: The script uses uv inline script metadata (notion-client>=3.0.0, httpx>=0.27). Dependencies are auto-installed on first uv run, no manual pip install needed.
  • Integration access: The integration must be connected to target pages/databases in Notion UI (Share → Connections → add integration)

CLI Script

Path: /var/minis/skills/notion-hub/scripts/notion_hub.py

Run: uv run --script --cache-dir /root/.cache/uv /var/minis/skills/notion-hub/scripts/notion_hub.py <command> [options]

Alias for brevity:

NH="uv run --script --cache-dir /root/.cache/uv /var/minis/skills/notion-hub/scripts/notion_hub.py"

Commands Reference

Search & Discovery

# Search everything
$NH search "meeting notes"
$NH search "project" --filter page
$NH search --filter database
$NH search "Q1" --sort descending --limit 5

# List users / get bot info
$NH users
$NH users --me

Pages — Read

# Get page properties (compact)
$NH page-get <page_id_or_url>
$NH page-get <page_id> --raw  # full API response

# Read page content as Markdown (best for AI consumption)
$NH page-read <page_id>
$NH page-read <page_id> --depth 5  # deeper recursion
$NH page-read <page_id> -o /var/minis/workspace/page.md  # save to file

# Accepts Notion URLs directly:
$NH page-read "https://notion.so/My-Page-abc123def456..."

Pages — Write

# Create page under another page
$NH page-create --page-id <parent_id> --title "New Page" --icon "📝"

# Create page in a database (= add row with content)
$NH page-create --database-id <db_id> --properties '{"Name":{"title":[{"text":{"content":"Task 1"}}]}}'

# Write Markdown content to a page
$NH page-write <page_id> --text "# Hello\n\nThis is a paragraph.\n\n- Item 1\n- Item 2"

# Write from file
$NH page-write <page_id> --file /var/minis/workspace/content.md

# Replace all existing content
$NH page-write <page_id> --text "Fresh content" --replace

# Update page properties
$NH page-update <page_id> --properties '{"Status":{"status":{"name":"Done"}}}'
$NH page-update <page_id> --icon "✅"
$NH page-update <page_id> --archived true  # archive page

Databases

# Get database schema (shows all properties, types, select options)
$NH db-get <database_id>
$NH db-get <database_id> --raw

# Query database rows
$NH db-query <database_id>
$NH db-query <database_id> --limit 20

# Query with filter
$NH db-query <database_id> --filter '{"property":"Status","status":{"equals":"In Progress"}}'

# Query with sort
$NH db-query <database_id> --sorts '[{"property":"Created","direction":"descending"}]'

# Compound filter
$NH db-query <db_id> --filter '{"and":[{"property":"Status","status":{"equals":"Done"}},{"property":"Priority","select":{"equals":"High"}}]}'

# Quick add a row (auto-detects property types from schema)
$NH db-add-row -d <database_id> --props '{"Name":"My Task","Status":"In Progress","Priority":"High","Due Date":"2024-03-15"}'
$NH db-add-row -d <database_id> --title "Simple row with just a title"

# Create a new database
$NH db-create --page-id <parent_page_id> --title "Task Tracker" --properties '{
  "Name": {"title": {}},
  "Status": {"status": {}},
  "Priority": {"select": {"options": [{"name":"High"},{"name":"Medium"},{"name":"Low"}]}},
  "Due Date": {"date": {}},
  "Tags": {"multi_select": {"options": [{"name":"Bug"},{"name":"Feature"}]}},
  "Assignee": {"people": {}},
  "Done": {"checkbox": {}}
}'

# Update database schema
$NH db-update <db_id> --title "New Title"
$NH db-update <db_id> --properties '{"New Column": {"rich_text": {}}}'

Blocks (Page Content)

# Get top-level blocks of a page
$NH blocks-get <page_id>
$NH blocks-get <page_id> --raw

# Get ALL blocks recursively (full page tree)
$NH blocks-get-all <page_id>
$NH blocks-get-all <page_id> --depth 5

# Append content
$NH block-append <page_id> --text "A new paragraph"
$NH block-append <page_id> --text "Item A\\nItem B\\nItem C" --type bulleted_list_item
$NH block-append <page_id> --blocks '[{"type":"heading_2","heading_2":{"rich_text":[{"text":{"content":"Section"}}]}},{"type":"paragraph","paragraph":{"rich_text":[{"text":{"content":"Content here"}}]}}]'

# Update a specific block
$NH block-update <block_id> --content '{"paragraph":{"rich_text":[{"text":{"content":"Updated text"}}]}}'

# Delete a block
$NH block-delete <block_id>

Comments

# List comments on a page
$NH comments-list <page_id>

# Add a comment to a page
$NH comment-create "This looks good!" --page-id <page_id>

# Reply in a discussion thread
$NH comment-create "Agreed" --discussion-id <discussion_id>

Notion Filter Syntax Quick Reference

// Text property
{"property": "Name", "rich_text": {"contains": "keyword"}}

// Select
{"property": "Status", "select": {"equals": "Done"}}

// Multi-select
{"property": "Tags", "multi_select": {"contains": "Bug"}}

// Status
{"property": "Status", "status": {"equals": "In Progress"}}

// Checkbox
{"property": "Done", "checkbox": {"equals": true}}

// Date
{"property": "Due", "date": {"before": "2024-04-01"}}
{"property": "Due", "date": {"on_or_after": "2024-01-01"}}

// Number
{"property": "Score", "number": {"greater_than": 80}}

// Compound (AND)
{"and": [{"property": "Status", "status": {"equals": "Done"}}, {"property": "Priority", "select": {"equals": "High"}}]}

// Compound (OR)
{"or": [{"property": "Status", "status": {"equals": "Done"}}, {"property": "Status", "status": {"equals": "Archived"}}]}

Notion Sort Syntax

[{"property": "Created", "direction": "descending"}]
[{"property": "Name", "direction": "ascending"}]
[{"timestamp": "last_edited_time", "direction": "descending"}]

Property Value Syntax for db-add-row --props

The --props JSON maps property names to simple values. The script auto-detects types from the database schema:

TypeValue formatExample
titlestring"My Title"
rich_textstring"Some text"
numbernumber42
selectstring (option name)"High"
multi_selectcomma-separated string or array"Bug,Feature" or ["Bug","Feature"]
statusstring (status name)"In Progress"
dateISO date string or {start, end}"2024-03-15"
checkboxbooleantrue
urlstring"https://..."
emailstring"[email protected]"
relationcomma-separated IDs or array"id1,id2"
peoplecomma-separated user IDs"user_id"
filesURL string or array of URLs"https://file.png"

Workflow Tips

  1. First time: Run $NH search or $NH search --filter database to discover accessible pages/databases and get their IDs.
  2. Before writing to a database: Run $NH db-get <id> to see the schema (property names, types, select options).
  3. Reading a page: Use page-read for Markdown output — much more readable than raw blocks.
  4. Writing a page: Use page-write --text with Markdown — the script auto-converts to Notion blocks.
  5. IDs: Both raw UUIDs and full Notion URLs are accepted for all ID parameters.
  6. Pagination: All list/query commands auto-paginate. Use --limit to cap results.

Error Handling

All errors return {"error": "..."} JSON. Common issues:

  • 401: Invalid or expired token
  • 403: Integration not connected to the target page/database
  • 404: Page/database not found or not accessible
  • 429: Rate limited (auto-retry is not implemented; wait and retry)

Security Notes

  • NOTION_API_KEY: Never echo, print, or expose the token value in conversation. Always reference via $NOTION_API_KEY.
  • User emails: The users command auto-masks email addresses (e.g. w***[email protected]). Do not attempt to retrieve or display full emails.
  • File URLs: Notion internal file URLs contain signed AWS tokens. The script auto-strips these from Markdown/block output. If you need to download a file, use blocks-get --raw and handle the URL in a script without printing it.
  • Recursion depth: blocks-get-all and page-read cap at depth 10 to prevent API call storms.