api-notion

name	api-notion
description	Notion REST API for pages, databases, blocks. Uses internal integration token for headless/CI. Activate for Notion operations.
allowed-tools	Bash, Read, Grep
user-invocable	true
quality_grade	B
quality_checked	"2026-03-19T00:00:00.000Z"

Notion API Skill

When to Activate

• Read/create/update pages
• Query databases
• Manage blocks and content
• Search workspace

Authentication

Credentials File: .credentials/notion.json

{
  "api_token": "ntn_..."
}

Create internal integration at: https://www.notion.so/my-integrations

Important: Pages must be shared with the integration to be accessible.

Load credentials before API calls:

NOTION_API_TOKEN=$(jq -r '.api_token' /Users/dhlee/Git/personal/neuron/.credentials/notion.json)

API Base URL

https://api.notion.com/v1

Required Headers

Authorization: Bearer $NOTION_API_TOKEN
Notion-Version: 2022-06-28
Content-Type: application/json

Common Operations

List Users

curl -s -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  https://api.notion.com/v1/users

Search

curl -s -X POST \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"query": "search term", "filter": {"property": "object", "value": "page"}}' \
  https://api.notion.com/v1/search

Get Page

curl -s -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  https://api.notion.com/v1/pages/{page_id}

Query Database

curl -s -X POST \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"property": "Status", "select": {"equals": "Done"}}}' \
  https://api.notion.com/v1/databases/{database_id}/query

Create Page in Database

curl -s -X POST \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "{database_id}"},
    "properties": {
      "Name": {"title": [{"text": {"content": "New page title"}}]},
      "Status": {"select": {"name": "In Progress"}}
    }
  }' \
  https://api.notion.com/v1/pages

Append Block Children

curl -s -X PATCH \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "New paragraph"}}]
        }
      }
    ]
  }' \
  https://api.notion.com/v1/blocks/{block_id}/children

Get Block Children

curl -s -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  "https://api.notion.com/v1/blocks/{block_id}/children?page_size=100"

Error Handling

Status	Meaning	Action
401	Invalid token	Check .credentials/notion.json
403	Page not shared	Share page with integration
404	Resource not found	Verify page/database ID
429	Rate limited	Wait and retry

Rate Limits

• 3 requests per second average
• Implement exponential backoff

References

• Notion API Docs