Notion

Notion

When to Use

Trigger phrases:

• "notion"
• "Help me with notion"

Use cases:

• When the task matches this skill's domain expertise

When NOT to use:

• For tasks outside this skill's scope

invoke with appropriate parameters

Advanced usage with options

invoke --option value --verbose

### Query via MCP

User: "Apa saja task yang overdue?" Vilona: Uses notion_search to find tasks, notion_fetch for details

### Create Page

User: "Buat meeting notes untuk meeting yesterday" Vilona: Uses notion_create_pages

## When NOT to Use

- When the tool already handles the workflow natively
- For personal preferences that do not affect output quality
- When the overhead of the system exceeds the time saved


## Overview

Notion serves as a unified workspace that combines notes, databases, wikis, calendars, and project management into a single platform. The Notion API (v1) provides programmatic access to every object in your workspace — pages, databases, blocks, users, and comments — enabling full CRUD automation. This skill covers the complete lifecycle of Notion automation: from integration setup and authentication through database querying, page creation, content publishing, and workspace-wide management.

The Notion API uses an internal_id-based addressing system where every page, database, and block is identified by a 32-character hex UUID. A database in Notion is both a container of pages AND a schema definition — each page in a database is a row whose properties (columns) conform to the database schema. This dual nature makes Notion databases powerful as lightweight application backends for content management, CRM, project tracking, and publishing workflows.

Key API capabilities include querying databases with rich filter and sort expressions, creating and updating pages with structured property values (text, select, multi-select, date, people, files, status, formula, relation, rollup), appending and modifying block children for rich document content, and searching the entire workspace. The API uses Bearer token authentication tied to a Notion integration (formerly called "bots") that must be explicitly granted access to each workspace and database.

Rate limiting is managed per-integration: 3 requests per second (RPS) burst, 90 requests per minute sustained. The API returns standard HTTP codes with detailed error JSON bodies. Pagination uses cursor-based keys with page_size parameters (default 100, max 100). Beyond basic CRUD, automation patterns include template-based page generation, bidirectional sync with external systems, bulk import/export workflows, and event-driven publishing via webhook polling or scheduled diffs.

## Daily Workflow

1. **Plan** — Review priorities and set daily objectives
2. **Execute** — Focus blocks with minimal interruptions
3. **Review** — End-of-day reflection and tomorrow's prep

## Frameworks

- **GTD (Getting Things Done)** — Capture, clarify, organize, reflect, engage
- **Pomodoro** — 25min focus + 5min break cycles
- **Eisenhower Matrix** — Urgent/Important prioritization
- **Time Blocking** — Dedicated blocks for deep work

## Tools

- Task management (Todoist, Notion, Linear)
- Calendar blocking for focus time
- Note-taking for capture and reference
- Automation for repetitive tasks

## Tips

- Batch similar tasks together
- Protect deep work time ruthlessly
- Review and adjust systems weekly
- Eliminate before optimizing


## Workflow

1. **Plan the data model** — Define database schemas (property types, relation links, formula fields). Map external data sources to Notion property types. Decide between single-page content and database-driven collections.

2. **Set up integration** — Create a Notion integration at https://www.notion.so/my-integrations. Copy the Internal Integration Secret (Bearer token). Share the target database or page with the integration from the Notion UI.

3. **Authenticate and connect** — Initialize the Notion client SDK or direct HTTP client with the Bearer token. Retrieve database metadata to confirm access. Parse the database schema to get property ID mappings.

4. **Query and transform data** — Build filtered queries using Notion's filter conditions (property filters, compound AND/OR). Process paginated results with cursor iteration. Transform API response data into the target format.

5. **Create or update pages** — Construct page create requests with correct property value formats. Handle nested block content for rich pages. Use page update (PATCH) for partial modifications. Implement idempotent upsert patterns using unique property lookups.

6. **Validate and inspect** — Read back created pages to confirm property values match. Verify block children render correctly. Test edge cases: empty values, long text truncation, relation targets, rollup recalculation.

7. **Automate and monitor** — Wrap the workflow in a scheduled task or webhook listener. Implement error handling for rate limit (429) and permission (403) responses. Add logging for each major step. Set up alerts for failures exceeding retry thresholds.

## Anti-Rationalization Table

| Rationalization | Reality |
|---|---|
| "I am too busy to organize" | Disorganization costs more time than organizing. Invest upfront. |
| "Multitasking is productive" | Context switching costs 25 minutes per switch. Focus on one thing. |
| "I will remember this" | You will not. Write it down. Externalize your memory. |
| "I can just manually update 10 records" | Manual updates are error-prone and don't scale. A 5-line script that runs in 2 seconds is safer and faster. |
| "The Notion API is too limited for real work" | The API covers all core objects: databases, pages, blocks, users, comments. Limitations (no webhooks, no file upload) can be bridged with polling and external storage. |
| "My integration token worked yesterday so it's fine" | Tokens can be invalidated by workspace admin actions, re-authorization, or permission changes. Always verify access with a test query before production runs. |


## Code Examples

### Query a Database with Filters
```python
from notion_client import Client

notion = Client(auth="ntn_xxxxx_secret")
database_id = "abc123def456"

# Filter for tasks with Status = "Done" and Priority = "High"
response = notion.databases.query(
    database_id=database_id,
    filter={
        "and": [
            {"property": "Status", "status": {"equals": "Done"}},
            {"property": "Priority", "select": {"equals": "High"}},
        ]
    },
    sorts=[{"property": "Due Date", "direction": "ascending"}],
    page_size=50,
)

for page in response["results"]:
    title = page["properties"]["Name"]["title"][0]["plain_text"]
    print(f"Task: {title}")
    next_cursor = response.get("next_cursor")
    if not next_cursor:
        break

Create a Page with Properties and Blocks

from notion_client import Client

notion = Client(auth="ntn_xxxxx_secret")

page = notion.pages.create(
    parent={"database_id": "abc123def456"},
    properties={
        "Name": {"title": [{"text": {"content": "Meeting Notes — Q4 Review"}}]},
        "Date": {"date": {"start": "2025-10-15", "end": None}},
        "Status": {"select": {"name": "In Progress"}},
        "Attendees": {"people": [{"id": "user-uuid-here"}]},
    },
    children=[
        {"heading_2": {"rich_text": [{"text": {"content": "Agenda"}}]}},
        {"bulleted_list_item": {"rich_text": [{"text": {"content": "Review Q4 metrics"}}]}},
        {"bulleted_list_item": {"rich_text": [{"text": {"content": "Set Q5 priorities"}}]}},
        {"divider": {}},
        {"paragraph": {"rich_text": [{"text": {"content": "Full notes will be shared separately."}}]}},
    ],
)
print(f"Created page: {page['url']}")

Upsert Page by Unique Property

def upsert_page(notion, database_id, unique_title, properties, children=None):
    """Create a page if it doesn't exist, otherwise update it."""
    existing = notion.databases.query(
        database_id=database_id,
        filter={"property": "Name", "title": {"equals": unique_title}},
    )
    if existing["results"]:
        page_id = existing["results"][0]["id"]
        notion.pages.update(page_id=page_id, properties=properties)
        print(f"Updated page: {page_id}")
        return page_id
    page = notion.pages.create(
        parent={"database_id": database_id},
        properties={
            "Name": {"title": [{"text": {"content": unique_title}}]},
            **properties,
        },
        children=children or [],
    )
    print(f"Created page: {page['id']}")
    return page["id"]

Append Blocks to an Existing Page

def append_toggle_section(notion, page_id, heading, body_lines):
    notion.blocks.children.append(
        block_id=page_id,
        children=[
            {"heading_3": {"rich_text": [{"text": {"content": heading}}]}},
            *[
                {"paragraph": {"rich_text": [{"text": {"content": line}}]}}
                for line in body_lines
            ],
        ],
    )

append_toggle_section(
    notion, "page-uuid-here",
    "Key Decisions",
    ["Decision 1: Use Notion as CMS", "Decision 2: Deploy via GitHub Actions"],
)

Setup / Configuration

Prerequisites

• A Notion workspace with admin or integration-grant access
• A Notion integration created at https://www.notion.so/my-integrations
• The Integration Token (Bearer token) from the integrations dashboard
• The target database or page shared with the integration (click Share → Invite → select your integration)
• Python 3.9+ with pip install notion-client

Environment Setup

export NOTION_TOKEN="ntn_xxxxx_secret"
export NOTION_DATABASE_ID="abc123def456"

SDK Initialization

import os
from notion_client import Client

notion = Client(auth=os.environ["NOTION_TOKEN"])

# Verify access by fetching database metadata
db = notion.databases.retrieve(os.environ["NOTION_DATABASE_ID"])
print(f"Connected to database: {db['title'][0]['plain_text']}")

Getting Property IDs

Notion uses property names in filter/query code but returns property data keyed by ID (a hashed string). Log the schema once to map names to IDs:

db = notion.databases.retrieve(database_id)
for prop_name, prop_meta in db["properties"].items():
    print(f"{prop_name} -> id={prop_meta['id']}  type={prop_meta['type']}")

Common Issues / Troubleshooting

Monetization

Process

Preparation

• Identify the automation target: database-backed collection, single-page content, or workspace-wide sync.
• Map the data model: list all property names, types, and expected value formats.
• Create the Notion integration and share it with target pages/databases.
• Install dependencies: pip install notion-client (or use raw HTTP with httpx).
• Verify connectivity with a test database retrieve or page fetch.

Execution

• Query existing data to confirm the filter and sort logic before creating or modifying.
• Use the upsert pattern (query by unique property → create or update) for idempotent operations.
• Append block children in batches of max 100 blocks per API call.
• Handle pagination with cursor iteration in a loop.
• Log each page created, updated, or skipped for audit trail.

Stewardship

• Monitor API usage to stay under rate limits (90 req/min). Schedule large imports during low-traffic windows.
• Rotate integration tokens periodically and update secrets in all consumers.
• Archive or unshare databases when automations are decommissioned to avoid stale permission warnings.
• Keep a schema registry (JSON file or Notion page) documenting all automated database schemas and their integration purposes.

Verification

• Integration token is valid and the target database/page is shared with the integration
• Database query with filters returns expected results (test with known data)
• Page creation completes with all properties populated correctly
• Block children render as expected (headings, paragraphs, lists, dividers)
• Upsert pattern works: first call creates, second call updates the same page
• Pagination handled correctly across all result pages
• Rate limit handling implemented with exponential backoff
• Error cases produce meaningful log messages
• Integration token stored securely (environment variable, vault, not hardcoded)