notion-pack

Use when standard Notion troubleshooting fails or you are chasing intermittent API errors — deep debugging for response inspection, permission chain tracing, property type mismatches, pagination edge cases, and block nesting limits. Trigger with phrases like "notion deep debug", "notion permission trace", "notion property mismatch", "notion pagination bug", "notion nesting limit".

Use when you are choosing or scaffolding how an app talks to Notion via the API — deciding between a headless CMS (blog/content site), a task tracker (project management), a knowledge base (wiki), a form-submission handler, or a data-pipeline source, and wiring the database schema plus integration code. Trigger with phrases like "notion cms", "notion headless blog", "notion task tracker", "notion wiki", "notion form handler", "notion data pipeline".

Integrate the Notion API into CI/CD pipelines for automated documentation sync, deploy tracking, and configuration reads. Use when setting up GitHub Actions workflows that push release notes to Notion, update database entries on deploy, create incident pages from CI, or read feature flags from Notion databases. Trigger with phrases like "notion CI", "notion GitHub Actions", "notion deploy sync", "notion release notes automation", "notion CI pipeline".

Diagnose and fix Notion API errors by HTTP status code and error code. Use when encountering Notion errors, debugging failed requests, or troubleshooting integration access, rate limiting, or validation issues. Trigger with phrases like "notion error", "fix notion", "notion not working", "debug notion", "notion 400", "notion 429".

Create, update, archive, and compose Notion pages and block content. Use when building pages programmatically, appending rich content blocks, updating page properties, or managing page lifecycle (archive/restore). Trigger with phrases like "notion create page", "notion add blocks", "notion update page", "notion archive page", "notion content", "notion block types", "notion rich text".

Query, filter, and manage Notion databases and pages. Use when building database queries with filters and sorts, creating/updating pages with typed properties, or reading page content. Trigger with phrases like "notion database query", "notion filter", "notion create page", "notion update properties", "notion CRUD".

Work with Notion blocks, rich text, comments, and page content. Use when you need to read a page's block tree, append formatted content (headings, lists, callouts, code), edit or delete blocks, build rich text with annotations, or manage page and block comments through the Notion API. Trigger with phrases like "notion blocks", "notion page content", "notion rich text", "notion comments", "notion append blocks".

Optimize Notion API usage to minimize rate-limit pressure, reduce engineering overhead, and maximize throughput. Use when auditing request volume, eliminating redundant API calls, implementing caching, or restructuring queries for efficiency. Trigger with "notion cost", "notion optimize", "notion API usage", "reduce notion requests", "notion rate limit budget", "notion efficient", "notion caching".

Implement data handling, PII protection, and GDPR/CCPA compliance for Notion integrations. Use when handling sensitive data from Notion pages, implementing data redaction, exporting or deleting a user's data on request, or ensuring compliance with privacy regulations. Trigger with phrases like "notion data", "notion PII", "notion GDPR", "notion data retention", "notion privacy", "notion CCPA".

Collect Notion API diagnostic info for troubleshooting and support tickets. Use when encountering persistent API issues, token/auth failures, page access problems, or preparing diagnostic bundles for Notion support. Trigger with phrases like "notion debug", "notion diagnostic", "notion support bundle", "collect notion logs", "notion troubleshoot".

Deploy Node.js applications that use the Notion API to production on Vercel, Railway, or Fly.io. Use when deploying Notion-powered backends, setting up NOTION_TOKEN in production secrets, configuring serverless singleton patterns, or adding health checks that verify Notion connectivity. Trigger with "deploy notion app", "notion production", "notion vercel deploy", "notion railway", "notion fly.io".

Configure Notion enterprise access control with OAuth, workspace permissions, and audit logging. Use when implementing OAuth public integrations, managing multi-workspace access, or building permission-aware Notion applications. Trigger with phrases like "notion SSO", "notion RBAC", "notion enterprise", "notion OAuth", "notion permissions", "notion multi-workspace".

Create a minimal working Notion API example. Use when starting a new Notion integration, testing your setup, or learning basic Notion API patterns (search, pages, users). Trigger with phrases like "notion hello world", "notion example", "notion quick start", "simple notion code", "first notion API call".

Execute Notion incident response procedures with triage, mitigation, and postmortem. Use when responding to Notion API outages, investigating errors, or running post-incident reviews for Notion integration failures. Trigger with phrases like "notion incident", "notion outage", "notion down", "notion on-call", "notion emergency", "notion broken".

Install and configure the Notion API SDK with authentication. Use when setting up a new Notion integration, configuring API tokens, or initializing @notionhq/client in your project. Trigger with phrases like "install notion", "setup notion", "notion auth", "configure notion API", "notion integration setup".

Use when debugging or reviewing Notion API code that fails with object_not_found, validation_error, rate_limited, or returns incomplete data. Covers the twelve most common mistakes: wrong page ID format (dashes), rich text array structure, block children not returned with page, pagination required for all lists, 3 req/sec shared across endpoints, and not sharing pages with the integration. Trigger with phrases like "notion mistakes", "notion pitfalls", "notion common errors", "notion gotchas", "notion debugging".

Use when you must move high volumes through the Notion API without tripping its 3 req/sec limit — bulk-creating pages, syncing 100K+ record databases, or running background jobs. Covers parallel requests within 3 req/sec, worker queues, database pagination at scale, incremental sync for large workspaces, and memory management for bulk operations. Trigger with phrases like "notion scale", "notion bulk operations", "notion high volume", "notion worker queue", "notion incremental sync".

Configure Notion local development with a dedicated dev integration, test mocking, and hot reload. Use when setting up a Notion development environment, writing tests for Notion code, or establishing a fast iteration cycle against the Notion API without risking production data. Trigger with "notion dev setup", "notion local development", "mock notion", "notion test environment".

Migrate data to/from Notion or between Notion workspaces with data mapping and validation. Use when migrating data into Notion databases, exporting from Notion, syncing between workspaces, or building ETL pipelines with Notion as source or destination. Trigger with phrases like "migrate notion", "notion migration", "import to notion", "export from notion", "notion data migration", "notion ETL".

Configure Notion integrations across development, staging, and production environments. Use when setting up multi-environment deployments, managing per-environment tokens, or implementing environment-specific Notion configurations. Trigger with phrases like "notion environments", "notion staging", "notion dev prod", "notion environment setup", "notion config by env".

Set up observability for Notion integrations with metrics, traces, and alerts. Use when implementing monitoring for Notion API calls, setting up dashboards, or configuring alerting for Notion integration health. Trigger with phrases like "notion monitoring", "notion metrics", "notion observability", "monitor notion", "notion alerts", "notion tracing".

Optimize Notion API performance with caching, batching, parallel requests, and incremental sync. Use when experiencing slow API responses, implementing caching strategies, reducing API call volume, or tuning request patterns for Notion integrations. Trigger with phrases like "notion performance", "optimize notion api", "notion latency", "notion caching", "notion slow", "notion batch requests", "notion incremental sync", "notion reduce api calls".

Use when you need to govern Notion integrations at scale — set integration naming standards, enforce page sharing policies, standardize property naming and database schemas, and run access audits that scan which bots can reach which pages. Trigger with phrases like "notion governance", "notion policy", "notion naming convention", "notion access audit", "notion schema standard".

Execute a Notion API production deployment checklist and readiness verification. Use when deploying Notion integrations to production, preparing for launch, verifying go-live readiness, or auditing an existing Notion integration. Trigger with "notion production checklist", "deploy notion integration", "notion go-live", "notion launch readiness", "notion prod audit".

Manage Notion API rate limits with exponential backoff, queue-based throttling, and batch optimization. Use when hitting 429 errors, implementing retry logic, or optimizing API request throughput for Notion integrations. Trigger with "notion rate limit", "notion 429", "notion retry", "notion backoff", "notion throttling", "notion too many requests", "notion queue".

Design and implement a production-ready Notion integration architecture with proper layering, caching, error handling, and testing strategies. Use when designing a new Notion integration, reviewing existing project structure, establishing architecture standards for a Notion application, or migrating from ad-hoc API calls to a layered architecture. Trigger with "notion architecture", "notion project structure", "notion reference architecture", "notion integration design", "notion layered architecture", or "notion service pattern".

Graceful degradation when Notion is down: offline cache, retry with exponential backoff, circuit breaker, health checks, and fallback content. Use when building fault-tolerant Notion integrations for production, or when a Notion outage is breaking your app. Trigger with phrases like "notion reliability", "notion circuit breaker", "notion offline fallback", "notion health check", "notion graceful degradation".

Apply production-ready @notionhq/client SDK patterns for TypeScript and Python. Use when implementing Notion integrations, building database queries with filters and sorts, handling pagination, constructing rich text blocks, or establishing team coding standards for Notion API usage. Trigger with "notion SDK patterns", "notion best practices", "notion code patterns", "idiomatic notion", "notion typescript", "notion python SDK".

Search Notion workspaces and retrieve pages, databases, and block content using the Notion API. Use when querying databases with filters, searching across a workspace, paginating large result sets, or extracting page content. Trigger with phrases like "notion search", "query notion database", "notion retrieve page", "notion pagination", "notion filter", "notion blocks", "notion get content".

Apply Notion API security best practices for integration tokens, OAuth2 flows, least-privilege capabilities, and page-level access control. Use when securing integration tokens, configuring OAuth2 for public integrations, rotating credentials, or auditing which pages an integration can access. Trigger with phrases like "notion security", "notion secrets", "secure notion", "notion API key security", "notion token rotation", "notion OAuth2", "notion permissions audit".

Upgrade @notionhq/client SDK versions and migrate between Notion API versions. Use when updating SDK packages, handling breaking changes between API versions, adopting new SDK features like comments API or status properties, or migrating Python notion-client. Trigger with phrases like "upgrade notion SDK", "notion migration", "notion breaking changes", "update notionhq client", "notion API version upgrade", "notion deprecation".

Build change detection and event handling for Notion workspaces using polling, native webhooks, and third-party connectors. Use when implementing real-time sync, change feeds, incremental backup, or event-driven workflows with Notion data. Trigger with phrases like "notion webhook", "notion events", "notion change detection", "notion polling", "notion sync changes", "notion real-time", "notion watch for changes".