notion

name	notion
version	0.1.0
author	devclaw
description	Notion API — create, read, search pages, databases, and blocks
category	productivity
tags	["notion","notes","database","wiki","project-management"]
requires	{"env":["NOTION_API_KEY"]}

Notion

Manage Notion pages, databases, and blocks via the REST API.

Setup

1. Check existing credentials:

   vault_get notion_api_key
   

2. If not configured:

   • Go to https://www.notion.so/my-integrations and create an integration
   • Copy the API key (starts with ntn_ or secret_)
   • Save to vault:

     vault_save notion_api_key "ntn-your-key-here"
     

   The key is auto-injected as $NOTION_API_KEY.

   • Important: Share target pages/databases with your integration (click "..." → "Connect to" → integration name)

API Basics

All requests need these headers:

curl -s "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

Search pages and databases

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "SEARCH_TERM"}' | jq '.results[] | {id, object: .object, title: (.properties.title.title[0].plain_text // .title[0].plain_text // "untitled")}'

Read a page

# Page properties
curl -s "https://api.notion.com/v1/pages/PAGE_ID" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" | jq '.properties'

# Page content (blocks)
curl -s "https://api.notion.com/v1/blocks/PAGE_ID/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" | jq '.results[] | {type, text: (.paragraph.rich_text[0].plain_text // .heading_1.rich_text[0].plain_text // .to_do.rich_text[0].plain_text // null)}'

Create a page

# In a database
curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "DATABASE_ID"},
    "properties": {
      "Name": {"title": [{"text": {"content": "Task title"}}]},
      "Status": {"select": {"name": "Todo"}}
    }
  }' | jq '{id, url}'

# Under another page
curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "PARENT_PAGE_ID"},
    "properties": {
      "title": [{"text": {"content": "New Page Title"}}]
    },
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Page content here."}}]}}
    ]
  }' | jq '{id, url}'

Query a database

curl -s -X POST "https://api.notion.com/v1/databases/DATABASE_ID/query" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "In Progress"}},
    "sorts": [{"property": "Created", "direction": "descending"}]
  }' | jq '.results[] | {id, title: .properties.Name.title[0].plain_text, status: .properties.Status.select.name}'

Add content to a page

curl -s -X PATCH "https://api.notion.com/v1/blocks/PAGE_ID/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "to_do", "to_do": {"rich_text": [{"text": {"content": "New task item"}}], "checked": false}}
    ]
  }'

Tips

• The Notion-Version header is required — use 2025-09-03 (latest).
• Database IDs and page IDs can be found in the URL: notion.so/workspace/PAGE_ID.
• Always search first to find the right page/database before creating new ones.
• The integration only sees pages that have been explicitly shared with it.
• For complex queries, use filters and sorts to narrow results.

Triggers

notion, add to notion, notion page, notion database, notion task, create page, search notion, adicionar no notion, buscar no notion, criar página