Skill v1.0.1
currentAutomated scan100/1001 files
version: "1.0.1" name: notion-management description: Complete guide for working with Notion API in Node.js/JavaScript projects. Use when creating, updating, fetching, or managing Notion pages, databases, and properties. Includes proper handling of rich text, database schemas, multi-select fields, dates, and complex content structures. Triggers on tasks like "create a Notion page," "update database properties," "add content to Notion," or "manage Notion workflows." license: MIT
Notion Management Skill
Master working with the Notion API for Node.js/JavaScript development. This skill provides patterns, tools, and references for all common Notion operations.
Quick Start
Fetching Notion Resources
// Fetch a page or databaseconst page = await notion_notion-fetch({id: "page-id-or-url"});// Pages return markdown content and properties// Databases return schema, data sources, and views
Creating Pages
// Single page creationconst pages = await notion_notion-create-pages({pages: [{properties: {title: "My Page Title",// Other properties based on database schema},content: "# Markdown content here\n\nSupports rich markdown."}],parent: {data_source_id: "collection-id" // or page_id, or database_id}});
Updating Pages
// Update propertiesawait notion_notion-update-page({page_id: "page-id",command: "update_properties",properties: {title: "Updated Title",status: "Done"}});// Replace all contentawait notion_notion-update-page({page_id: "page-id",command: "replace_content",new_str: "# New content here"});// Replace specific sectionawait notion_notion-update-page({page_id: "page-id",command: "replace_content_range",selection_with_ellipsis: "# Old heading...last paragraph.",new_str: "# New heading\nNew content"});// Insert content after a sectionawait notion_notion-update-page({page_id: "page-id",command: "insert_content_after",selection_with_ellipsis: "## Section...end of section.",new_str: "\n## New Section\nNew content here"});
Common Property Types and Formats
Simple Properties
- title (string): Page title, shown as large heading
- rich_text (string): Text field
- url (string): URL field
- email (string): Email field
- phone_number (string): Phone number
- checkbox (string): Use
"__YES__"or"__NO__" - number (number): Use JavaScript numbers, not strings
Select Properties
// single_select: Just use the option nameproperties: {Status: "In Progress" // Must match exact option name}// multi_select: Single string or comma-separated// ❌ WRONG: ["option1", "option2"] // Don't use arrays// ❌ WRONG: "option1,option2" // Don't use commas// ✅ CORRECT: Need to use separate API calls or specific format
Date Properties
// Date properties use expanded format with three keysproperties: {"date:Due Date:start": "2025-01-30","date:Due Date:end": null, // Optional end date"date:Due Date:is_datetime": 0 // 0 for date, 1 for datetime}
Place Properties
// Place/location properties use expanded formatproperties: {"place:Office:name": "HQ","place:Office:address": "123 Main St","place:Office:latitude": 37.7749,"place:Office:longitude": -122.4194,"place:Office:google_place_id": "optional-id"}
Special Property Names
Properties named "id" or "url" (case-insensitive) must be prefixed with "userDefined:":
properties: {"userDefined:id": "value","userDefined:URL": "https://example.com"}
Multi-Select Fields - CRITICAL
Common mistake: Multi-select fields have strict validation. When creating or updating pages in a database with multi_select properties:
- Fetch the database first to see available options:
``typescript const db = await notion_notion-fetch({ id: "database-id" }); // Response shows: "Tags": {"options": [{"name": "Option1"}, {"name": "Option2"}]} ``
- Use only valid option names:
``typescript properties: { Tags: "Option1" // Single option as string } ``
- For multiple options: Currently the API has limitations. Best practice:
- Create the page with one tag
- Update it with additional tags if needed
- Or pass multiple tags separated by specific format (check database schema)
- Error handling: If you get "Invalid multi_select value", check:
- Is the option name spelled exactly as shown in database?
- Are you passing a string, not an array?
- Does the database schema allow this option?
Database Operations
Fetch Database Schema
const db = await notion_notion-fetch({id: "database-id-or-url"});// Returns:// - Database title and icon// - Data sources (collections) within the database// - Schema for each data source// - Views available
Creating Databases
const db = await notion_notion-create-database({title: [{type: "text", text: {content: "My Database"}}],parent: {page_id: "parent-page-id"},properties: {"Task Name": {type: "title"},"Status": {type: "select",select: {options: [{name: "To Do", color: "red"},{name: "In Progress", color: "yellow"},{name: "Done", color: "green"}]}},"Due Date": {type: "date"}}});
Updating Database Schema
await notion_notion-update-database({database_id: "db-id",title: [{type: "text", text: {content: "New Title"}}],properties: {"New Property": {type: "rich_text"},"Property to Rename": {name: "Renamed Property"},"Property to Delete": null // Set to null to remove}});
Content (Markdown) Guidelines
Supported Markdown
- Headings:
# H1,## H2, etc. - Lists: Unordered
- item, ordered1. item - Code: Inline `
code` and code blocks - Bold/Italic:
**bold**,*italic* - Links:
[text](url) - Tables: Full markdown table support
- Quotes:
> quoted text - Toggles/Collapsible:
▶ Collapsed content\n\tHidden items(Note: indentation with tabs)
Toggle/Collapsible Sections
Toggles are created with the ▶ character followed by content that should be hidden:
▶ Click to expandHidden content line 1Hidden content line 2-Nested list item
Important: Content after ▶ must be indented with tabs or spaces.
Rich Text Annotations
Content can include color and style annotations:
# Heading {color="blue"}Some text {color="red"} and {bold="true"}
Search and Navigation
Search Notion
const results = await notion_notion-search({query: "search term",query_type: "internal" // or "user" for user search});// Filter by creation dateconst filtered = await notion_notion-search({query: "recent docs",filters: {created_date_range: {start_date: "2025-01-01",end_date: "2025-01-31"}}});
Fetch Teams and Users
// List teamsconst teams = await notion_notion-get-teams({query: "engineering" // optional search});// List usersconst users = await notion_notion-get-users({query: "john", // optional searchpage_size: 100});// Get specific userconst user = await notion_notion-get-users({user_id: "user-id-or-self"});
Error Handling
Common Errors and Solutions
"Invalid multi_select value"
Cause: Option name doesn't exist or format is wrong Solution:
- Fetch database to see valid options
- Use exact option names
- Pass as string, not array
"Invalid input" / Validation error
Cause: Wrong property format or type Solution:
- Check property type in database schema
- Use correct format (e.g., date properties need date:Property:start format)
- Verify special names use userDefined: prefix
"Page not found"
Cause: Wrong ID or insufficient permissions Solution:
- Verify page/database ID is correct
- Check you have access to the resource
- Use full URL if ID doesn't work
"Unauthorized"
Cause: Notion integration doesn't have permission Solution:
- Verify integration is shared with the database/page
- Check integration scopes in Notion settings
- Re-authenticate if needed
Best Practices
- Always fetch first: Before creating content in a database, fetch the database to understand its schema
- Validate option names: Multi-select options are strictly validated—check exact spellings
- Use data_source_id for databases: When a database has multiple data sources, use
data_source_idinstead ofdatabase_idas parent - Handle IDs flexibly: Most tools accept page IDs with or without dashes
- Content indentation: Toggle/collapsible content must use tabs or spaces for indentation
- Break up complex updates: Large content updates are safer when split into smaller operations
- Test with simple cases first: Before complex automation, test with a single page/field
- Document environment: Store Notion integration tokens securely, never in git
Advanced Patterns
See references/advanced-patterns.md for:
- Batch operations and performance optimization
- Syncing external data to Notion
- Creating dynamic databases and views
- Handling relationships and rollups
- Complex filtering and sorting