Getting started

Learn how to make your first API requests using the Notion API

If you're new to the Notion API, you've come to the right place.

Intro to our developer resources

Getting started

In this guide you'll learn how to use the Notion JavaScript client library to add an entry to a database in your Notion workspace.

📘

Before you start

Make sure you are an Admin user in your Notion workspace. If you're not an Admin in your current workspace, create a new personal workspace for free.

Step 1: Create an integration.

  • Go to https://www.notion.com/my-integrations.
  • Click the "+ New integration" button.
  • Give your integration a name - I chose "Vacation Planner".
  • Select the workspace where you want to install this integration.
  • Select the capabilities that your integration will have.
  • Click "Submit" to create the integration.
  • Copy the "Internal Integration Token" on the next page and save it somewhere secure, e.g. a password manager.
929929

Step 2: Share a database with your integration

Integrations don't have access to any pages (or databases) in the workspace at first. A user must share specific pages with an integration in order for those pages to be accessed using the API. This helps keep you and your team's information in Notion secure.

Start from a new or existing page in your workspace. Insert a new database by typing /database and selecting a full page table. Give it a title. I've called mine "Destinations". Click on the ••• Page menu and use the search bar in the Add connections pop-out to find the integration you've created. Simply click on your integration to give it access to your database.

960960

Creating and sharing a database with your integration

Your integration now has the requested permissions on the new database. Once an integration is added to a workspace, any member can share pages and databases with that integration - there's no requirement to be an Admin for this step.

Before moving on, you need the ID of the database you just created.
Copy the URL of your Notion database. Make sure you're viewing the database as a full page if you're using an inline database.
If you're using the Notion desktop app, click on the Share button and select Copy link.

The database ID is the part of the URL after your workspace name (if you have one) and the slash (myworkspace/) and before the question mark (?). The ID is 32 characters long, containing numbers and letters. Copy the ID and paste it somewhere you can easily find later.

https://www.notion.so/myworkspace/a8aec43384f447ed84390e8e42c2e089?v=...
                                  |--------- Database ID --------|

Step 3: Add an item to a database

To use Notion's JavaScript library, you need to have npm and node.js installed. Alternatively, you can also use the cURL example to make the HTTP request directly.

Open your terminal, create a project directory, and save your Notion API key (from Step 1) and the Database ID (from Step 2) as environment variables.

mkdir notion-example
cd notion-example
export NOTION_KEY=secret_...
export NOTION_DATABASE_ID=...

Create an index.js file and a package.json file in your directory as shown in the example files below:

import { Client } from "@notionhq/client"

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

const databaseId = process.env.NOTION_DATABASE_ID

async function addItem(text) {
  try {
    const response = await notion.pages.create({
      parent: { database_id: databaseId },
      properties: {
        title: { 
          title:[
            {
              "text": {
                "content": text
              }
            }
          ]
        }
      },
    })
    console.log(response)
    console.log("Success! Entry added.")
  } catch (error) {
    console.error(error.body)
  }
}

addItem("Yurts in Big Sur, California")
{
  "name": "notion-example",
  "type": "module",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "dependencies": {
    "@notionhq/client": "^1.0.1"
  } 
}
curl -X POST https://api.notion.com/v1/pages \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2021-08-16" \
  --data "{
    \"parent\": { \"database_id\": \"$NOTION_DATABASE_ID\" },
    \"properties\": {
      \"title\": {
        \"title\": [
          {
            \"text\": {
              \"content\": \"Yurts in Big Sur, California\"
            }
          }
        ]
      }
    }
  }"

Install the client library, then run the script. Now switch back to Notion, and the new item will appear in your database!

npm install
node index.js

📘

No new item appearing in the database?

Let's check for some common causes:

  • First, try reloading the browser or app. If the item appears, you're good to go.
  • What was the output in your terminal? If you see a message that starts with {"object":"error",..., then there's something wrong with your request. Double check that your API token and Database ID are correct. Check that you've performed the steps above correctly and try again.
  • If you're still experiencing an issue, reach out to [email protected]

Next steps

👩‍💻Check out more in-depth code examples to get up and running.

📤 Try many more endpoints in the Notion API using our Postman collection.

🖥 Watch these video tutorials on how to use Notion's API:

👥 Are you building an integration for users across many workspaces? Learn how to to create a public integration using OAuth.


Did this page help you?