| name | notion-hello-world |
| description | 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".
|
| allowed-tools | Read, Write, Edit |
| version | 1.38.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","productivity","notion"] |
| compatibility | Designed for Claude Code |
Notion Hello World
Overview
Three minimal examples covering the Notion API core surfaces: searching for pages, creating a test page in a database, and verifying the created page by retrieving it back.
Prerequisites
- Completed
notion-install-auth setup
NOTION_TOKEN environment variable set (internal integration token from https://www.notion.so/my-integrations)- At least one database shared with your integration via the Connections menu
- Node.js 18+ with
@notionhq/client or Python 3.8+ with notion-client
Authentication
Every request authenticates with your internal integration token via the
NOTION_TOKEN environment variable — the client reads it as
new Client({ auth: process.env.NOTION_TOKEN }) (or Python's
Client(auth=os.environ["NOTION_TOKEN"])). Generate the token at
notion.so/my-integrations, then share each
target database with the integration through its Connections menu. Never hardcode
the token — keep it in the environment. See notion-install-auth for the full setup.
Instructions
The workflow is three steps against the Notion API core surfaces. Instantiate the
client once, then search, create, and verify. Step 1's skeleton is below; the full
create + verify code (with block content, title extraction, and metadata) is in
the implementation walkthrough.
Step 1: Search for pages
The search endpoint queries across everything your integration can access;
filter narrows to pages (use value: 'database' for databases).
import { Client } from '@notionhq/client';
const notion = new Client({ auth: process.env.NOTION_TOKEN });
const { results } = await notion.search({
query: 'meeting notes',
: { : , : },
: ,
});
