Quick Reference

Fresh Fast lookup for Notion API essentials.

Available References

Reference	Description
Endpoints	All API endpoints with methods and URLs
Objects	Object schemas and property types
Errors	Error codes and solutions
Troubleshooting	Common issues and fixes

Quick Links

Authentication

const { Client } = require('@notionhq/client');
const notion = new Client({ auth: process.env.NOTION_API_KEY });

Base URL

https://api.notion.com/v1

Required Headers

Header	Value
Authorization	Bearer secret_xxxxx
Notion-Version	2022-06-28
Content-Type	application/json

Common Operations

Create Page

await notion.pages.create({
  parent: { database_id: 'xxx' },
  properties: {
    Name: { title: [{ text: { content: 'Title' } }] }
  }
});

Query Database

await notion.databases.query({
  database_id: 'xxx',
  filter: {
    property: 'Status',
    select: { equals: 'Done' }
  }
});

Update Page

await notion.pages.update({
  page_id: 'xxx',
  properties: {
    Status: { select: { name: 'Done' } }
  }
});

Get Page

await notion.pages.retrieve({
  page_id: 'xxx'
});

Append Blocks

await notion.blocks.children.append({
  block_id: 'xxx',
  children: [
    { paragraph: { rich_text: [{ text: { content: 'Hello!' } }] } }
  ]
});

Rate Limits

Metric	Limit
Requests per second	3
Requests per minute	~180
Page size (pagination)	100 max

ID Formats

• Page ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (UUID with dashes)
• Database ID: Same format as Page ID
• Block ID: Same format as Page ID
• User ID: Same format as Page ID

ID Normalization

IDs can be 32 characters (no dashes) or 36 characters (with dashes). The API accepts both formats.

API Versioning

Current stable version: 2022-06-28

Always include the Notion-Version header to ensure consistent behavior.