notion-api

robBowes 的头像作者 robBowes

Interact with Notion project boards via the Notion API. Use when Claude needs to list, read, create, or update tickets/items on a Notion project board, change ticket status, or filter items by state or project. Supports querying databases, reading page content, updating properties, and creating new items.

📖 中文导读:Interact with Notion project boards via the Notion API. Use when Claude needs to list, read, create, or update tickets/items on a Notion project board, change ticket status, or filter items by state or project. Supports querying databases, reading page content, updating properties, and creating new items. 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: notion-api description: Interact with Notion project boards via the Notion API. Use when Claude needs to list, read, create, or update tickets/items on a Notion project board, change ticket status, or filter items by state or project. Supports querying databases, reading page content, updating properties, and creating new items.

Notion API Skill

Interact with Notion project boards to manage tickets and tasks.

Prerequisites

  • NOTION_API_KEY environment variable set with an integration token from https://www.notion.so/my-integrations
  • tsx in PATH (install globally: pnpm add -g tsx)
  • The integration must be connected to the workspace containing the target databases

Vessel Workspace Databases

Database ID Description
Tasks a5a500207a95402fad259d6487646cef Main tasks/tickets database

Quick Commands for Vessel Tasks

# List tasks in a project
~/.claude/skills/notion-api/scripts/list-items.ts --database a5a500207a95402fad259d6487646cef --project "Autonomous Reporting Extraction"

# List tasks by status
~/.claude/skills/notion-api/scripts/list-items.ts --database a5a500207a95402fad259d6487646cef --status "Not Started"

# Read a specific task (accepts URL or ID)
~/.claude/skills/notion-api/scripts/read-item.ts --page 'https://www.notion.so/vesselfunds/Task-Name-abc123'

Available Scripts

All scripts are in ~/.claude/skills/notion-api/scripts/ and directly executable (require tsx in PATH).

All scripts accept Notion URLs or raw IDs - they auto-extract the ID from URLs.

Script Purpose
list-items.ts List/filter items from a database
read-item.ts Read full content of a page
create-item.ts Create new item in database
update-item.ts Update page properties
change-status.ts Change status of an item
delete-item.ts Delete (archive) a page
append-content.ts Add markdown content to a page
manage-blocks.ts List/delete/update page blocks
add-comment.ts Add a comment to a page
batch.ts Batch operations (export, status)
page-to-md.ts Save page as markdown file
append-task.ts Create task with due date
search-pages.ts Search pages by keyword
sync-changes.ts Sync pages to local markdown folder
export-db.ts Export database as CSV/MD/JSON
clone-page.ts Deep clone page content
track-progress.ts Summarize status of database items
quick-note.ts Rapidly create page with title+content

Quick Reference

List items with filters

~/.claude/skills/notion-api/scripts/list-items.ts --database <DB_ID|URL> [--status "Done"] [--project "SOC 2"] [--limit 20]

Read item content

~/.claude/skills/notion-api/scripts/read-item.ts --page <PAGE_ID|URL>

Update item properties

~/.claude/skills/notion-api/scripts/update-item.ts --page <PAGE_ID|URL> --property Status --value "Done"
~/.claude/skills/notion-api/scripts/update-item.ts --page <PAGE_ID|URL> --title "New title"

Create new item

~/.claude/skills/notion-api/scripts/create-item.ts --database <DB_ID|URL> --title "Task name" [--status "Not Started"] [--assign "Person Name"]

Change status

~/.claude/skills/notion-api/scripts/change-status.ts --page <PAGE_ID|URL> --status "Done"

Delete a page

~/.claude/skills/notion-api/scripts/delete-item.ts --page <PAGE_ID|URL>

Add a comment

~/.claude/skills/notion-api/scripts/add-comment.ts --page <PAGE_ID|URL> "Your comment text"

Append content to a page (markdown)

# Inline markdown (positional argument)
~/.claude/skills/notion-api/scripts/append-content.ts --page <PAGE_ID|URL> "# Hello World"

# From a file
~/.claude/skills/notion-api/scripts/append-content.ts --page <PAGE_ID|URL> --file content.md

# Pipe via stdin (NO --file flag, just pipe directly)
echo '# Heading' | ~/.claude/skills/notion-api/scripts/append-content.ts --page <PAGE_ID|URL>

# Heredoc via stdin (NO --file flag)
~/.claude/skills/notion-api/scripts/append-content.ts --page <PAGE_ID|URL> << 'EOF'
# Heading
- Bullet 1
- Bullet 2
EOF

IMPORTANT: Do NOT use --file - for stdin. The script auto-reads stdin when no --file or positional content is provided.

Supported markdown: # h1, ## h2, ### h3, - bullets, 1. numbered, > quotes, --- dividers, code blocks

Manage page blocks

# List all blocks with their IDs
~/.claude/skills/notion-api/scripts/manage-blocks.ts --page <PAGE_ID|URL> --action list

# Delete a block
~/.claude/skills/notion-api/scripts/manage-blocks.ts --page <PAGE_ID|URL> --action delete --block <BLOCK_ID>

# Update block text
~/.claude/skills/notion-api/scripts/manage-blocks.ts --page <PAGE_ID|URL> --action update --block <BLOCK_ID> --text "New text"

Batch operations

# Export all items to JSON
~/.claude/skills/notion-api/scripts/batch.ts export --database <DB_ID|URL> --output backup.json

# Mark filtered items as done
~/.claude/skills/notion-api/scripts/batch.ts mark-done --database <DB_ID|URL> --filter-status "In Progress"

# Count items by status
~/.claude/skills/notion-api/scripts/batch.ts count --database <DB_ID|URL>

Page to Markdown

# Save to file
~/.claude/skills/notion-api/scripts/page-to-md.ts --page <PAGE_ID|URL> --output notes.md

# Include properties in output
~/.claude/skills/notion-api/scripts/page-to-md.ts --page <PAGE_ID|URL> --include-properties > page.md

Append Task (with due date)

~/.claude/skills/notion-api/scripts/append-task.ts --database <DB_ID|URL> --title "Review PR" --due 2025-01-15

# With date range
~/.claude/skills/notion-api/scripts/append-task.ts -d <DB_ID> -t "Sprint" --due "2025-01-20 to 2025-01-24" --status "Not Started"

Search Pages

~/.claude/skills/notion-api/scripts/search-pages.ts --query "meeting notes"

# Filter by type
~/.claude/skills/notion-api/scripts/search-pages.ts --query "Q4 planning" --filter page --limit 20

Sync to Local

# Sync a page and subpages to local folder
~/.claude/skills/notion-api/scripts/sync-changes.ts --page <PAGE_ID|URL> --local ./docs

# Sync entire database
~/.claude/skills/notion-api/scripts/sync-changes.ts --database <DB_ID|URL> --local ./wiki --depth 3

Export Database

# CSV export
~/.claude/skills/notion-api/scripts/export-db.ts --database <DB_ID|URL> --format csv --output tasks.csv

# Markdown export with content
~/.claude/skills/notion-api/scripts/export-db.ts --database <DB_ID|URL> --format md --output ./docs --include-content

# JSON export
~/.claude/skills/notion-api/scripts/export-db.ts --database <DB_ID|URL> --format json > backup.json

Clone Page

# Clone to another database
~/.claude/skills/notion-api/scripts/clone-page.ts --page <PAGE_ID|URL> --target-db <DB_ID|URL>

# Clone as child of another page
~/.claude/skills/notion-api/scripts/clone-page.ts --page <PAGE_ID|URL> --target-page <PAGE_ID|URL>

Track Progress

# Summary by status
~/.claude/skills/notion-api/scripts/track-progress.ts --database <DB_ID|URL>

# Group by different property
~/.claude/skills/notion-api/scripts/track-progress.ts --database <DB_ID|URL> --group-by "Priority"

Quick Note

# Create in database
~/.claude/skills/notion-api/scripts/quick-note.ts --database <DB_ID|URL> --title "Meeting Notes" "Discussed roadmap"

# Create under page
~/.claude/skills/notion-api/scripts/quick-note.ts --page <PAGE_ID|URL> --title "Ideas" "Random thoughts"

# Pipe content
echo "Long content here" | ~/.claude/skills/notion-api/scripts/quick-note.ts -d <DB_ID> -t "From stdin"

URL Handling

Scripts automatically extract IDs from Notion URLs:

# All of these work:
~/.claude/skills/notion-api/scripts/read-item.ts --page abc123def456
~/.claude/skills/notion-api/scripts/read-item.ts --page 'https://www.notion.so/workspace/Page-Title-abc123def456'
~/.claude/skills/notion-api/scripts/read-item.ts --page 'https://www.notion.so/workspace/Parent-Page-xxx?p=abc123def456'

Property Types Reference

See references/property-types.md for handling different Notion property types when updating.

Common Patterns

Filter by multiple criteria

~/.claude/skills/notion-api/scripts/list-items.ts --database $DB_ID --status "Not Started" --project "SOC 2"

Batch status update (using zx)

import { $ } from "zx";
const pages = ["id1", "id2", "id3"];
for (const id of pages) {
  await $`~/.claude/skills/notion-api/scripts/change-status.ts --page ${id} --status "Done"`;
}

Error Handling

Scripts exit with code 1 on error and print JSON error details. Common issues:

  • 401: Invalid or missing API key
  • 404: Page/database not found or not shared with integration
  • 400: Invalid property name or value format