Quickstart

Get up and running with the Notion SDK in minutes

Before you begin, make sure you’ve followed Notion’s Getting Started Guide to create an integration and obtain an API token.

Installation

First, install the Notion SDK:

npm install @notionhq/client

Initialize the Client

Import and initialize a client using your integration token:

CommonJS

const { Client } = require("@notionhq/client")

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

import { Client } from "@notionhq/client"

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

import { Client } from "@notionhq/client"

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

Never hardcode your API token directly in your code. Always use environment variables or a secure configuration management system.

Make Your First API Call

Once initialized, you can make requests to any Notion API endpoint. Here’s an example that lists all users in your workspace:

;(async () => {
  const listUsersResponse = await notion.users.list({})
  console.log(listUsersResponse)
})()

Example Response

Each method returns a Promise that resolves with the API response:

{
  "results": [
    {
      "object": "user",
      "id": "d40e767c-d7af-4b18-a86d-55c61f1e39a4",
      "type": "person",
      "person": {
        "email": "[e-mail]"
      },
      "name": "Avocado Lovelace",
      "avatar_url": "https://secure.notion-static.com/e6a352a8-8381-44d0-a1dc-9ed80e62b53d.jpg"
    }
  ]
}

Query a Data Source

Here’s a more advanced example that queries a data source with filters:

const myPage = await notion.dataSources.query({
  data_source_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  filter: {
    property: "Landmark",
    rich_text: {
      contains: "Bridge",
    },
  },
})

Endpoint parameters are grouped into a single object. You don’t need to remember which parameters go in the path, query, or body.

Complete Example

Here’s a complete working example that creates a new page in a database:

1. Set up your environment

   Create a .env file in your project root:

   NOTION_TOKEN=secret_your_integration_token_here
   DATABASE_ID=your_database_id_here
   
2. Create your script

   Create a file called create-page.js:

   const { Client } = require("@notionhq/client")
   
   const notion = new Client({
     auth: process.env.NOTION_TOKEN,
   })
   
   async function createPage() {
     try {
       const response = await notion.pages.create({
         parent: {
           database_id: process.env.DATABASE_ID,
         },
         properties: {
           Name: {
             title: [
               {
                 text: {
                   content: "My New Page",
                 },
               },
             ],
           },
         },
       })
       
       console.log("Page created successfully!")
       console.log("Page ID:", response.id)
     } catch (error) {
       console.error("Error creating page:", error.message)
     }
   }
   
   createPage()
   
3. Run your script

   Execute the script:

   node create-page.js
   

Error Handling

Always wrap your API calls in try-catch blocks to handle errors gracefully:

const { Client, APIErrorCode } = require("@notionhq/client")

try {
  const notion = new Client({ auth: process.env.NOTION_TOKEN })
  const myPage = await notion.dataSources.query({
    data_source_id: dataSourceId,
    filter: {
      property: "Landmark",
      rich_text: {
        contains: "Bridge",
      },
    },
  })
} catch (error) {
  if (error.code === APIErrorCode.ObjectNotFound) {
    // Handle by asking the user to select a different data source
    console.error("Data source not found")
  } else {
    // Other error handling code
    console.error(error)
  }
}

The SDK provides typed error codes through the APIErrorCode enum, making it easy to handle specific error scenarios.

Available Endpoints

The client provides access to all Notion API endpoints through intuitive namespaces:

• notion.blocks - Block CRUD operations
• notion.databases - Database CRUD operations
• notion.dataSources - Data source operations and querying
• notion.pages - Page CRUD operations
• notion.users - User listing and retrieval
• notion.comments - Comment CRUD operations
• notion.fileUploads - File upload lifecycle management
• notion.search() - Search across workspace

For a complete list of available methods and parameters, see the API Reference.

Next Steps

Authentication

Learn about authentication options including OAuth

Error Handling

Master error handling with typed error codes

TypeScript Support

Leverage full TypeScript support and type guards

Examples

Explore more examples in the Notion Cookbook