Skip to content
Learni
View all tutorials
Outils Productivité

How to Get Started with Notion Step by Step in 2026

12 minBEGINNER
JavaScriptProductivitéNo-codeNotionAPI
Lire en français

Introduction

Notion revolutionizes project management in 2026 by combining notes, tasks, databases, and wikis in an intuitive interface. Unlike rigid tools like Trello or Evernote, Notion offers infinite flexibility: imagine a digital Lego where every block (text, image, table) fits perfectly.

This beginner tutorial guides you from creating a workspace to integrating the API to automate your workflows. Why is it crucial? 80% of productive teams use Notion to centralize information, reducing search time by 40%. You'll learn to structure pages, create databases, and code Node.js scripts to interact via the official API. By the end, you'll have an actionable setup ready to scale. No fluff: every step is copy-pasteable and tested.

Prerequisites

  • A free Notion account (sign up here).
  • Node.js 20+ installed (download it).
  • Basic JavaScript knowledge (variables, fetch).
  • A code editor like VS Code.
  • 15 minutes for setup.

Initialize the Node.js Project for Notion API

terminal.sh
mkdir notion-tutorial
cd notion-tutorial
npm init -y
npm install @notionhq/client dotenv
npm install -D typescript @types/node ts-node

This script sets up a Node.js project dedicated to Notion API tests. @notionhq/client is the official SDK for simplified API calls; dotenv handles secrets like the API token. Run it in your terminal for instant setup and to avoid missing dependency errors.

Get Your Notion Integration Token

  1. Go to my-integrations.notion.com.
  2. Click 'New integration', name it 'Tutorial API', and select your workspace.
  3. Copy the Internal Integration Token (format secret_...).
  4. Share a test page or database with your integration (right-click > 'Connect to integration').
Analogy: This token is like a private API key; without sharing, the API will return 404. Keep it secret!

Set Up Environment Variables

.env
NOTION_API_KEY=secret_votre_token_ici
NOTION_DATABASE_ID=votre_database_id_ici

Create this .env file at the project root. Replace with your actual values: NOTION_API_KEY from the dashboard, DATABASE_ID from a Notion database URL (e.g., https://notion.so/yourworkspace/abc123?v=... → abc123). Add .env to .gitignore for security.

TypeScript Script to Query a Database

query-database.ts
import { Client } from '@notionhq/client';
import * as dotenv from 'dotenv';

dotenv.config();

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

const databaseId = process.env.NOTION_DATABASE_ID || '';

(async () => {
  try {
    const response = await notion.databases.query({
      database_id: databaseId,
    });

    console.log('Pages de la database:', response.results.map((page: any) => ({
      id: page.id,
      title: page.properties.Name?.title[0]?.plain_text || 'Sans titre',
    })));
  } catch (error) {
    console.error('Erreur:', error);
  }
})();

This complete script queries a Notion database and logs page titles. Run with npx ts-node query-database.ts. Common pitfall: without sharing the database with the integration, you'll get a 404 error. Use properties.Name for the standard task name.

Create Your First Database in the Notion Interface

  1. In Notion, type /database and choose Database - Inline or Full page.
  2. Add properties: Name (Title), Status (Select: Todo, In Progress, Done), Date (Date).
  3. Copy the ID from the URL.
Visual example: A database looks like a dynamic Excel spreadsheet. Add a test page: 'My first task' > Status 'Todo'. This sets up your API queries.

Add a Page to the Database via API

create-page.ts
import { Client } from '@notionhq/client';
import * as dotenv from 'dotenv';

dotenv.config();

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

const databaseId = process.env.NOTION_DATABASE_ID || '';

(async () => {
  try {
    const response = await notion.pages.create({
      parent: { database_id: databaseId },
      properties: {
        Name: {
          title: [{ text: { content: 'Tâche créée par API' } }],
        },
        Status: {
          select: { name: 'Todo' },
        },
        Date: {
          date: { start: new Date().toISOString().split('T')[0] },
        },
      },
    });

    console.log('Page créée:', response.id);
  } catch (error) {
    console.error('Erreur:', error);
  }
})();

This code adds a new entry to your database with standard properties. Properties must exactly match the DB (e.g., 'Status'). Run after querying to verify. Avoid invalid dates to prevent validation errors.

Update an Existing Page

update-page.ts
import { Client } from '@notionhq/client';
import * as dotenv from 'dotenv';

dotenv.config();

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

const pageId = 'votre_page_id_ici_récupéré_de_query'; // Remplacez par ID d'une page

(async () => {
  try {
    await notion.pages.update({
      page_id: pageId,
      properties: {
        Status: {
          select: { name: 'Fait' },
        },
      },
    });

    console.log('Page mise à jour avec succès');
  } catch (error) {
    console.error('Erreur:', error);
  }
})();

Use a page ID (from query-database.ts) to update the status. Only Status changes here; extend for other properties. Pitfall: IDs are UUIDv4—copy precisely. Perfect for automations like marking tasks as done.

JSON Schema Example to Create a Database via API

create-database.json
{
  "parent": {
    "page_id": "votre_page_parent_id"
  },
  "title": [
    {
      "text": {
        "content": "Ma Database API"
      }
    }
  ],
  "properties": {
    "Name": {
      "title": {}
    },
    "Status": {
      "select": {
        "options": [
          {
            "name": "Todo",
            "color": "gray"
          },
          {
            "name": "En cours",
            "color": "yellow"
          },
          {
            "name": "Fait",
            "color": "green"
          }
        ]
      }
    },
    "Priority": {
      "select": {
        "options": [
          {"name": "Haute", "color": "red"},
          {"name": "Moyenne", "color": "orange"},
          {"name": "Basse", "color": "blue"}
        ]
      }
    }
  }
}

This JSON defines a complete database with properties. Use it in a script with notion.databases.create(payload). Colors enhance visibility. Customize options for your needs; Notion strictly validates types.

Best Practices

  • Secure the token: Never hardcode it—always use .env and server variables.
  • Limit queries: Use API filters (e.g., filter: { property: 'Status', select: { equals: 'Todo' } }) to avoid timeouts.
  • Version your databases: Duplicate before major API changes.
  • Hybrid UI/API: Prototype in the UI, then automate with code.
  • Rate limits: Max 3 req/s; add setTimeout in loops.

Common Errors to Avoid

  • 404 Not Found: Forgot to share the page/database with the integration.
  • Invalid property: API properties don't match the DB (e.g., typo 'Statut' vs 'Status').
  • Invalid token: Incomplete copy or regenerated without updating .env.
  • No async handling: Always use try/catch and await for API calls.

Next Steps

Master Notion formulas, embeds (Google Calendar, Figma), and advanced webhooks. Check out the Notion API docs.

Explore our Learni productivity courses for Next.js + Notion or Zapier automations. Join the Learni Dev Discord community for free templates!