Quick Start Guide

Fresh Get your first Notion integration running in under 5 minutes.

Prerequisites

• A Notion account
• Node.js installed (v14+)
• Workspace Owner permissions (or create a new workspace)

Step 1: Create an Integration

1. Go to notion.so/profile/integrations
2. Click + New integration
3. Enter a name and select your workspace
4. Click Submit and copy your Internal Integration Secret

Keep Your Secret Safe

Never commit your API secret to version control. Use environment variables instead.

Step 2: Install the SDK

npm install @notionhq/client dotenv

Step 3: Set Up Environment Variables

Create a .env file in your project root:

NOTION_API_KEY=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NOTION_PAGE_ID=your-page-id-here

Finding Page IDs

The page ID is the 32-character string at the end of any Notion page URL: https://notion.so/My-Page-**abc123def456...**

Step 4: Grant Integration Access

Your integration needs explicit permission to access pages:

1. Open a Notion page
2. Click ... (More menu) in the top-right
3. Select + Add connections
4. Find and select your integration

Step 5: Make Your First Request

Create index.js:

require('dotenv').config();
const { Client } = require('@notionhq/client');

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

async function main() {
  // Get the bot user
  const me = await notion.users.me({});
  console.log('Connected as:', me.name);

  // Retrieve a page
  const page = await notion.pages.retrieve({
    page_id: process.env.NOTION_PAGE_ID
  });
  console.log('Page title:', page.properties.title?.title?.[0]?.plain_text);
}

main().catch(console.error);

Run it:

node index.js

Step 6: Query a Database

const response = await notion.databases.query({
  database_id: 'your-database-id',
  filter: {
    property: 'Status',
    select: {
      equals: 'Done'
    }
  },
  sorts: [
    {
      property: 'Created',
      direction: 'descending'
    }
  ]
});

console.log(`Found ${response.results.length} pages`);

Step 7: Create a Page

const newPage = await notion.pages.create({
  parent: { database_id: 'your-database-id' },
  properties: {
    Name: {
      title: [{ text: { content: 'My New Page' } }]
    },
    Status: {
      select: { name: 'In Progress' }
    },
    Tags: {
      multi_select: [
        { name: 'API' },
        { name: 'Tutorial' }
      ]
    }
  }
});

console.log('Created page:', newPage.url);

Next Steps

Now that you have a working integration, explore these resources:

• SOP 001: Create Integration - Detailed setup guide
• SOP 003: Create Database - Database creation workflow
• Workflow: CMS Integration - Build a headless CMS

Common Issues

Issue	Solution
401 Unauthorized	Check your API key is correct
404 Not Found	Ensure integration has page access
429 Rate Limited	Implement retry with backoff
Invalid Request	Verify required properties exist

Official Resources

• Notion SDK for JavaScript
• API Reference
• Postman Collection