our-claude-skills/ourdigital-custom-skills/01-notion-organizer/code/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