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 )
• 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',
  filter: { property: 'object', value: 'page' },
  page_size: 5,
});

Step 2: Create a test page

pages.create adds a row to a target database. The properties object must match

the database schema — Name with type title is the only universally required

property. An optional children array appends block content (headings, paragraphs,

to-dos) at creation time. Full code is in the

implementation walkthrough.

Step 3: Verify by retrieving the page

pages.retrieve fetches the full page object, confirming creation and exposing

createdtime, lastedited_time, url, and the complete properties map. Full

code is in the implementation walkthrough.

Output

• Search results listing pages your integration can access
• Newly created page in the target database with title and block content
• Verification output confirming the page exists with correct metadata

Error Handling

Examples

Two complete, runnable scripts chain all three operations end to end — connect,

search, find a database, create a page, and verify it. Here is the shape of the

TypeScript version:

const notion = new Client({ auth: process.env.NOTION_TOKEN });
await notion.users.list({});                 // 1. verify connectivity
await notion.search({ query: 'test' });      // 2. search
const page = await notion.pages.create({ /* ... */ });  // 3. create
await notion.pages.retrieve({ page_id: page.id });      // 4. verify

Full copy-paste scripts for both languages — the complete TypeScript main() and

the equivalent Python program — live in runnable examples.

Resources

• Notion API Getting Started
• Search Endpoint Reference
• Create a Page Reference
• Retrieve a Page Reference
• Working with Page Content

Next Steps

Once these three calls succeed, proceed to notion-local-dev-loop to set up a

development workflow with live reload and environment management. From there,

notion-database-query covers filtering and sorting rows, and notion-block-content

covers appending richer block structures to pages you create.