our-claude-skills/ourdigital-custom-skills/02-notion-organizer/references/reference.md

Notion Organizer Reference

Notion API Fundamentals

Base Configuration

• Base URL: https://api.notion.com
• Current Version: 2022-06-28
• Authentication: Bearer token in Authorization header

Rate Limits

Limit	Value	Strategy
Requests/second	3 (average)	Use throttling/semaphore
Burst allowed	Small bursts	Implement exponential backoff
Page size	100 items max	Use pagination cursors
Payload size	500KB max	Split large operations

Core Object Hierarchy

Workspace
└── Database (container)
    └── Page (row)
        └── Block (content)

Property Types Reference

Type	Use Case	Notes
title	Page name	Required, one per database
rich_text	Text content	Max 2,000 chars
number	Numeric values	Supports format options
select	Single choice	Define options array
multi_select	Multiple choices	Define options array
status	Workflow states	Groups: To-do, In progress, Complete
date	Dates/times	ISO 8601 format
checkbox	Boolean	true/false
url	Links	Max 2,000 chars
email	Email addresses	Validation applied
phone_number	Phone	String format
relation	Links to pages	Requires database_id
rollup	Aggregated data	Requires relation + function
formula	Computed values	Expression syntax
files	Attachments	External URLs or Notion hosted
people	User references	Notion user IDs
created_time	Auto timestamp	Read-only
created_by	Auto user	Read-only
last_edited_time	Auto timestamp	Read-only
last_edited_by	Auto user	Read-only

Size Limits

Element	Limit
Rich text content	2,000 characters
URL length	2,000 characters
Array elements	100 items
Page properties	100 per page
Database properties	100 per database

Error Codes

Code	Status	Action
rate_limited	429	Wait Retry-After header seconds
validation_error	400	Check request body format
object_not_found	404	Verify sharing/permissions
unauthorized	401	Check API token validity
conflict_error	409	Resource was modified, refetch
internal_server_error	500	Retry with backoff

---

Workflow Patterns

Pattern 1: Database Audit

Purpose: Analyze database structure and recommend optimizations

Steps:

1. Fetch database schema via MCP or API
2. Analyze property types, naming conventions, usage
3. Identify issues:
   • Unused properties
   • Inconsistent naming
   • Suboptimal property types
   • Missing relations
4. Present recommendations with rationale
5. Execute approved changes incrementally

Example Query:

Audit my "Projects" database:
- Check for unused properties
- Identify naming inconsistencies
- Recommend schema optimizations

Pattern 2: Bulk Reorganization

Purpose: Move/update many pages efficiently

Decision Tree:

• ≤ 50 operations → Use MCP tools with staged execution

• 50 operations → Generate Python script

Steps:

1. Assess scope (count affected pages)
2. Estimate API calls and time
3. Choose execution method (MCP vs Python)
4. Execute with progress updates
5. Generate summary report

Example Query:

Move all pages with status "Archived" from "Active Projects"
to "Archive" database, preserving the Project Name and Date properties

Pattern 3: Schema Migration

Purpose: Transfer data between databases with different schemas

Steps:

1. Fetch source database schema
2. Fetch target database schema
3. Create property mapping plan:
   • Direct mappings (same type)
   • Transformations needed (type conversion)
   • Unmappable properties (manual handling)
4. Validate compatibility
5. Execute migration:
   • MCP for small datasets
   • Python for large datasets
6. Verify data integrity

Property Mapping Template:

Source Property → Target Property (Transformation)
─────────────────────────────────────────────────
Name (title)    → Project Name (title)     [Direct]
Status (select) → Stage (status)           [Map values]
Due Date (date) → Deadline (date)          [Direct]
Tags (multi)    → Categories (multi)       [Merge options]
Notes (text)    → Description (text)       [Direct]
Owner (text)    → Assignee (people)        [Manual]

Pattern 4: Property Cleanup

Purpose: Standardize properties across databases

Common Tasks:

• Rename properties to consistent convention (camelCase, snake_case, Title Case)
• Consolidate duplicate select/multi-select options
• Remove unused properties
• Add missing required properties

Naming Convention Guide:

Recommended: Title Case with spaces
Examples: "Project Name", "Due Date", "Status", "Assigned To"

Alternative: camelCase (for technical databases)
Examples: "projectName", "dueDate", "status", "assignedTo"

Pattern 5: Duplicate Detection

Purpose: Find and handle duplicate or similar content

Detection Strategies:

1. Exact title match
2. Fuzzy title similarity (Levenshtein distance)
3. Property combination match (e.g., same name + date)
4. Content hash comparison

Resolution Options:

• Merge: Combine properties from duplicates
• Archive: Move older duplicate to archive
• Delete: Remove with user confirmation
• Link: Create relation between related items

---

MCP Tool Usage Examples

Search for Pages

Use mcp__notion__search to find:
- Query: "marketing campaign"
- Filter: database_id = "abc123"

Query Database with Filters

Use mcp__notion__query-database:
- Database ID: "abc123"
- Filter: { "property": "Status", "select": { "equals": "Active" } }
- Sorts: [{ "property": "Created", "direction": "descending" }]

Update Page Properties

Use mcp__notion__update-page:
- Page ID: "xyz789"
- Properties: {
    "Status": { "select": { "name": "Completed" } },
    "Completed Date": { "date": { "start": "2025-12-05" } }
  }

Create New Page

Use mcp__notion__create-page:
- Parent: { "database_id": "abc123" }
- Properties: {
    "Name": { "title": [{ "text": { "content": "New Project" } }] },
    "Status": { "select": { "name": "Planning" } }
  }

---

Best Practices

1. Always Fetch Before Modify

Never assume database structure. Always retrieve current schema first.

2. Batch Operations Wisely

• Group related updates
• Use pagination for queries
• Implement checkpoints for large operations

3. Handle Relations Carefully

• Relations require both databases to be accessible
• Synced databases need special handling
• Rollups depend on relations - update order matters

4. Preserve Data Integrity

• Back up critical data before major changes
• Use transactions where possible
• Verify changes after execution

5. Respect User Permissions

• Check integration has access to target resources
• Request additional permissions when needed
• Document permission requirements