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:
const { Client } = require("@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": "[email protected]"
},
"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:
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
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()
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 operationsnotion.databases - Database CRUD operationsnotion.dataSources - Data source operations and queryingnotion.pages - Page CRUD operationsnotion.users - User listing and retrievalnotion.comments - Comment CRUD operationsnotion.fileUploads - File upload lifecycle managementnotion.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
