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.
- Learn the Notion API: start with Introduction to the Notion API, then explore block text parsing or large data source queries.
- Build an API integration: create a web form, connect GitHub issues, or send email notifications.
- Bring external data into Notion: use a Worker sync for GitHub issues and pull requests, GitHub stars, HubSpot, Intercom, Linear, PagerDuty, Readwise and Reader, Salesforce, Sentry, Todoist, Zendesk and more.
- Give a Notion Agent a reliable new capability: execute a repeatable API workflow in one tool call, or connect to Airflow, Vega-lite charts, CloudWatch Logs, Postgres, Snowflake query, PowerPoint creator, Vercel, and more.
- React to external events: receive and verify Zendesk webhooks.
Tell the agent the outcome or integration you need, then point it to:
catalog.json, the machine-readable index of every runnable project and its supported commands.AGENTS.md, the canonical instructions for finding, running, adapting, adding, and validating recipes.- The selected project's README and entrypoint, which are authoritative for its setup and implementation.
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."
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:1Other API examples use different scripts and may require additional services.
Use the command in the selected example's README rather than assuming
npm start.
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-queryAfter 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.
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 |
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.
| Task | Worker |
|---|---|
| Scaffold a new Worker from the base template | Default Worker template |
| 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 |
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 |
| Task | Worker | Integration |
|---|---|---|
| Verify ticket events and upsert tickets and comments | Zendesk webhook | Zendesk |
- Developer guides — including the Notion MCP client integration guide
- Agent skills — reusable workflows for working with Notion
- Notion developer documentation
- Notion API reference
- Contributing — add or improve an example, Worker, skill, or guide
This project is licensed under the MIT License.