d0nghyun/api-notion

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