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

Stay in touch

Join the Notion developer community on Slack and sign up for our developer newsletter mailing list.

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.
  • 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.

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 /table and selecting a full page table. Give it a title. I've called mine "Weekend getaway destinations". Click on the Share button and use the selector to find your integration by its name, then click Invite.

Creating and sharing a database with your integrationCreating and sharing a database with your integration

Creating and sharing a database with your integration

Your integration now has permission to read, write, and edit 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": "^0.1.9"
  } 
}
curl -X POST https://api.notion.com/v1/pages \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2021-05-13" \
  --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, click Help in the footer.

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.

Updated 3 days ago


Getting started


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

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.