Accessing a Notion Database Using the API

Set up a Notion API integration, make a database connection, and write a Node.js script that retrieves an ID value for a Notion database from the API.

This is part of a four-part series on showing the potential of Notion as a CMS for complex websites:

  1. Using Notion Callouts to Generate Complex Components
  2. Accessing a Notion Database Using the API
  3. Write Notion Page and Block Data to JSON File with Node.js
  4. Transform Notion API Data into Component-Ready JSON

Working with a Notion database using the API is pretty straightforward once you get going. But there's some setup to get started.

Create Notion Integration

Begin by going to My Integrations and clicking New Integration.

Set the following information:

  • Name
  • Logo (optional)
  • Choose the appropriate workspace
  • Desired capabilities

If you're following the four-part tutorial, we only need content capabilities. We will not be working with comments or users.

Make a Connection

With many APIs, this is enough to have the access you need. But with Notion, you have to make a connection between the integration and the database.

Here's how you create a connection:

  1. Click the options menu when viewing the database.
  2. Choose Add Connections.
  3. Search or scroll for your connection, and confirm the choice.

Find the Database ID

To be able to find and work with content in the database, you have to know the ID. This also isn't as simple as it seems like it might be. The ID doesn't come from the ID, but is an internal database ID that has to be retrieved through the API.

We'll write a Node.js script to help us.

Install Dependencies

Let's install the Node SDK.

npm install @notionhq/client

Get API Key

Your API key is listed on the integration detail page. You can get to each integration from My Integrations.


Store sensitive values like this as environment variables. In the example below, I'm accessing this value via a NOTION_API_KEY environment variable.

Write the Script

To find the database, we have to use the search method.

Here is a basic snippet that uses a query passed when running the script. The script loops through all results and print the title and ID for each database returned from the search.

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

// Exit if no query is provided
const query = process.argv[2];
if (!query) {
console.log("Please provide a query");

const notion = new Client({ auth: process.env.NOTION_API_KEY });

async function getDatabaseId() {
const response = await notion.search({
filter: { property: "object", value: "database" },
response.results.map((result) =>
console.log(`${result.title[0].plain_text} -> ${result.id}`)


Running the script with a query matching the title of your database should produce at least one proper result. Assuming the script is called index.js, usage would look something like this:

> node index.js "My Database"

[My Database] xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
[My Other Database] xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx

You can then use the proper ID to access pages, blocks, and more within the database.

Example Code

Here is a full example similar to the script above, using dotenv to load the secret key.

If you're following the four-part series, move on to Part 3 to write a script that retrieves page and block content from Notion.

Let's Connect

Keep Reading

Write Notion Page and Block Data to JSON File with Node.js Script

Write a Node.js script that connects to a Notion database and writes its page and block content to a local JSON file.

Apr 02, 2023

Using Notion Callouts to Generate Complex Components

Exploring a theoretical approach to enabling Notion to serve as a CMS for complex websites with interactive components.

Mar 31, 2023

Transform Notion API Data into Component-Ready JSON

Take raw JSON output from the Notion API and transform it into properties that can be used by your website’s pages and components.

Apr 03, 2023