Notion hello world

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',
  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 created_time, last_edited_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

Error	HTTP Code	Cause	Solution
unauthorized	401	Invalid or expired token	Verify NOTION_TOKEN value at notion.so/my-integrations
object_not_found	404	Page/database not shared with integration	Add your integration via the page's Connections menu (... > Connect to)
validation_error	400	Property name/type mismatch	Retrieve the database schema with databases.retrieve first
rate_limited	429	Exceeded 3 requests/second	Wait for Retry-After header value, then retry
conflict_error	409	Transaction conflict	Retry the request after a brief delay

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.