Skip to main content

Notion SDK for JavaScript

A simple and easy-to-use client for the Notion API. Build powerful integrations with type-safe TypeScript support, automatic retries, and comprehensive error handling.

Get StartedAPI Reference

Quick Start

Get up and running with the Notion SDK in minutes

1

Install the package

Install the Notion SDK using your preferred package manager:
npm install @notionhq/client
2

Create an integration

Go to Notion’s developer portal and create a new integration to get your API token. Make sure to grant the integration the necessary permissions for your use case.
Store your API token securely as an environment variable. Never commit it to version control.
3

Initialize the client

Import and initialize the client with your integration token:
const { Client } = require('@notionhq/client')

const notion = new Client({
  auth: process.env.NOTION_TOKEN
})
4

Make your first request

Start making requests to the Notion API:
const response = await notion.users.list({})
console.log(response.results)

{
  "results": [
    {
      "object": "user",
      "id": "d40e767c-d7af-4b18-a86d-55c61f1e39a4",
      "type": "person",
      "person": {
        "email": "[email protected]"
      },
      "name": "Jane Doe"
    }
  ]
}

Explore by Topic

Learn about the key features and capabilities of the SDK

Authentication

Set up OAuth flows and manage API tokens for your integration

Error Handling

Handle errors gracefully with type-safe error codes and utilities

TypeScript Support

Leverage full TypeScript type definitions for all API operations

Pagination

Efficiently iterate through large result sets with built-in utilities

Automatic Retries

Automatic retry logic for rate limits and transient server errors

Type Guards

Distinguish between full and partial API responses with type guards

API Resources

Explore the complete API reference for all available endpoints

Pages

Create, retrieve, update, and move pages within your Notion workspace

Explore pages API

Blocks

Manage block content including CRUD operations and children management

Explore blocks API

Databases

Query, create, and update databases with powerful filtering and sorting

Explore databases API

Search

Search across pages and databases in your Notion workspace

Explore search API

Ready to build with Notion?

Join thousands of developers building powerful integrations with the Notion API. From simple automation to complex applications, the Notion SDK makes it easy.

Start Building

Build docs developers (and LLMs) love

Get started for freeTalk to us