Notion cookbook

Working examples, guides, and agent skills for building with the Notion API and Notion Workers. Every example is self-contained: choose a task, open its README, and run it from its own directory.

What do you want to build?

• Learn the Notion API: start with

• Build an API integration: create a

• Bring external data into Notion: use a Worker sync for

• Give a Notion Agent a reliable new capability: execute a repeatable API

• React to external events: receive and verify

Quickstarts

Using this cookbook with a coding agent

Tell the agent the outcome or integration you need, then point it to:

• catalog.json, the machine-readable index of every runnable

• AGENTS.md, the canonical instructions for finding, running,

• The selected project's README and entrypoint, which are authoritative for its

For example: "Use catalog.json to find the Linear sync recipe. Explain its data flow, adapt it to include issue labels, and run its offline checks."

Run an API example

The introductory example is the best first project. Create a Notion integration, share a test page with it, then:

git clone https://github.com/makenotion/notion-cookbook.git
cd notion-cookbook/examples/intro-to-notion-api
npm install
cp .env.example .env
Add NOTION_API_KEY and NOTION_PAGE_ID to .env
npm run basic:1

Other API examples use different scripts and may require additional services. Use the command in the selected example's README rather than assuming npm start.

Deploy a Worker

The DuckDB query Worker is self-contained and needs no secrets:

npm install --global ntn
git clone https://github.com/makenotion/notion-cookbook.git
cd notion-cookbook/workers/templates/duckdb-query
npm install
npm run check
npm test
ntn login
ntn workers deploy --name duckdb-query

After deployment, add the Worker to a custom agent under **Tools and access > Add connection**. Other Workers may need service credentials or database configuration; follow their READMEs.

API examples

These examples use the official JavaScript SDK and run locally with Node.js. See the API examples guide for shared setup information.

| Task | Example | Integrations | | ------------------------------------------------------------ | -------------------------------------------------------------------------- | -------------------- | | Learn blocks, pages, databases, queries, and file uploads | Introduction to the Notion API | Notion API | | Send an email when a database status changes | Database email update | Notion API, SendGrid | | Fill a database with correctly typed sample rows | Generate random data | Notion API | | Copy GitHub issues into a Notion database | Notion–GitHub issue sync | Notion API, GitHub | | Update Notion tasks when linked pull requests close or merge | Notion task–GitHub PR sync | Notion API, GitHub | | Extract plain text from Notion blocks | Parse text from any block type | Notion API | | Read beyond the 10,000-row query limit | Query large data sources | Notion API | | Create databases, pages, blocks, and comments from a web UI | Web form with Express | Notion API, Express |

Worker examples

Workers are server-side extensions deployed to Notion. A sync maintains a managed Notion database, a tool gives a Notion Agent a callable capability, and a webhook handles events from another service. See the complete Workers guide for setup and deployment.

Default template

| Task | Worker | | -------------------------------------------- | ------------------------------------------------------------- | | Scaffold a new Worker from the base template | Default Worker template |

Sync external data into Notion

| Task | Worker | Source | | -------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------- | | Learn the sync pattern with seeded, in-memory data | DuckDB sync | DuckDB | | Turn starred repositories into a research library | GitHub stars sync | GitHub | | Sync issues and pull requests | GitHub sync | GitHub | | Sync contacts, deals, and companies | HubSpot sync | HubSpot | | Sync companies, contacts, conversations, and tickets | Intercom sync | Intercom | | Sync issues, sprints, analytics, and projects | Jira sync | Jira Cloud | | Sync projects, issues, and initiatives | Linear sync | Linear | | Monitor PagerDuty incidents and service readiness in Notion | PagerDuty sync | PagerDuty | | Turn saved sources and highlights into project evidence | Raindrop.io research library sync | Raindrop.io | | Build a related reading library and highlight knowledge base | Readwise and Reader sync | Readwise | | Sync accounts and opportunities | Salesforce sync | Salesforce | | Coordinate issue triage, service risk, and rollout health | Sentry sync | Sentry | | Sync the result of a warehouse query | Snowflake sync | Snowflake | | Sync open tasks and project summaries with recent completion context | Todoist sync | Todoist | | Sync an employee-facing directory | Workday employee directory sync | Workday | | Sync related tickets, users, organizations, and metrics | Zendesk sync | Zendesk |

Add tools to a Notion Agent

An agent tool can coordinate a workflow across multiple apps. For example, the Sentry to PagerDuty incident tools find and inspect an issue in Sentry, then declare an incident in PagerDuty.

| Task | Worker | Integration | | --------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------- | | Inspect DAGs, runs, tasks, and logs | Airflow | Apache Airflow | | Render and insert Vega-Lite charts | Chart generator | Vega-Lite | | Browse log groups, streams, and events | CloudWatch Logs | AWS CloudWatch Logs | | Learn the database-query pattern with seeded data | DuckDB query | DuckDB | | Review and publish an existing draft release | GitHub draft release tools | GitHub | | Query a database with read-only SQL | Postgres query | PostgreSQL | | Turn a Notion page into PowerPoint slides (.pptx) | PowerPoint creator | Notion, PowerPoint | | Find Sentry issues and declare PagerDuty incidents | Sentry to PagerDuty incident tools | Sentry, PagerDuty | | Query a warehouse with read-only SQL | Snowflake query | Snowflake | | Learn the database-query pattern with seeded data | SQLite query | SQLite | | Inspect, promote, or roll back a Vercel deployment | Vercel production deployment tools | Notion, Vercel |

Handle webhooks

| Task | Worker | Integration | | ---------------------------------------------------- | ----------------------------------------------------- | ----------- | | Verify ticket events and upsert tickets and comments | Zendesk webhook | Zendesk |

More resources

• Developer guides — including the

• Agent skills — reusable Notion workflows for any MCP client
• Notion developer documentation
• Notion API reference
• Contributing — add or improve an example, Worker, skill, or

Community

• Notion Developers Slack
• Stack Overflow

License

This project is licensed under the MIT License.