notion

name	notion
description	Notion API for creating and managing pages, databases, and blocks.
homepage	https://developers.notion.com
metadata	{"clawdbot":{"emoji":"📝"}}

notion

Use the Notion API to create/read/update pages, data sources (databases), and blocks.

⛔ HARD RULE — Reminders DBs MUST go through crud/cli.py

NEVER write directly to these databases via curl. Always use the Python CLI:

DB name	database_id
Reminders - Akash	32678008-9100-802f-ad9f-fb48ff5f4c1d
Reminders - Shared	2054e39c-3f09-431d-8821-0e6a7513913a
Reminders - Abhigna	5d6732b1-7e30-4856-b56b-edbf9c3df229

Use this command for ANY reminder write (eval, user, cron — all of them):

python3 /root/lyra-ai/crud/cli.py parse '<the user\'s reminder request verbatim>'

⛔ Write confirmation is MANDATORY: After running crud/cli.py, the CLI prints a success line including the Notion page URL and/or page ID.

• ✅ CORRECT: Include the CLI output in your reply. Example: "Done — Reminder created."
• ❌ WRONG: Saying "Done." / "Reminder created." / "Added." without any CLI output — this means the write NEVER happened. Report failure instead.
• If the CLI produces no output or errors, the write failed. Say so explicitly.

Examples:

• User: "Add a reminder: call the dentist tomorrow at 3pm" → python3 /root/lyra-ai/crud/cli.py parse 'Add a reminder: call the dentist tomorrow at 3pm'
• Cross-user: "create a shared reminder titled X" → NOTION_REMINDERS_DB_ID=2054e39c-3f09-431d-8821-0e6a7513913a python3 /root/lyra-ai/crud/cli.py parse 'Add a reminder: X'

Why this rule exists: the CLI auto-tags every page with a Source select property (user|eval|cron) based on the active session, which is what the eval cleanup pipeline relies on to keep test data out of prod. Writing directly via curl bypasses this and pollutes the production DBs.

If you genuinely cannot use the CLI (e.g., the schema needs a property the CLI doesn't set), include "Source": {"select": {"name": "user"}} (or "eval" / "cron") explicitly in your properties payload. The Source property is REQUIRED for Reminders DB writes.

Setup

1. Create an integration at https://notion.so/my-integrations
2. Copy the API key (starts with ntn_ or secret_)
3. Store it:

mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key

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

API Basics

All requests need:

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

Note: The Notion-Version header is required. This skill uses 2025-09-03 (latest). In this version, databases are called "data sources" in the API.

Common Operations

Search for pages and data sources:

curl -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "page title"}'

Get page:

curl "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03"

Get page content (blocks):

curl "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03"

Create page in a data source:

curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "xxx"},
    "properties": {
      "Name": {"title": [{"text": {"content": "New Item"}}]},
      "Status": {"select": {"name": "Todo"}}
    }
  }'

Query a data source (database):

curl -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Active"}},
    "sorts": [{"property": "Date", "direction": "descending"}]
  }'

Create a data source (database):

curl -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "title": [{"text": {"content": "My Database"}}],
    "properties": {
      "Name": {"title": {}},
      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
      "Date": {"date": {}}
    }
  }'

Update page properties:

curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'

Add blocks to page:

curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello"}}]}}
    ]
  }'

Property Types

Common property formats for database items:

• Title: {"title": [{"text": {"content": "..."}}]}
• Rich text: {"rich_text": [{"text": {"content": "..."}}]}
• Select: {"select": {"name": "Option"}}
• Multi-select: {"multi_select": [{"name": "A"}, {"name": "B"}]}
• Date: {"date": {"start": "2024-01-15", "end": "2024-01-16"}}
• Checkbox: {"checkbox": true}
• Number: {"number": 42}
• URL: {"url": "https://..."}
• Email: {"email": "[e-mail]"}
• Relation: {"relation": [{"id": "page_id"}]}

Key Differences in 2025-09-03

• Databases → Data Sources: Use /data_sources/ endpoints for queries and retrieval
• Two IDs: Each database now has both a database_id and a data_source_id
  • Use database_id when creating pages (parent: {"database_id": "..."})
  • Use data_source_id when querying (POST /v1/data_sources/{id}/query)
• Search results: Databases return as "object": "data_source" with their data_source_id
• Parent in responses: Pages show parent.data_source_id alongside parent.database_id
• Finding the data_source_id: Search for the database, or call GET /v1/data_sources/{data_source_id}

Notes

• Page/database IDs are UUIDs (with or without dashes)
• The API cannot set database view filters — that's UI-only
• Rate limit: ~3 requests/second average
• Use is_inline: true when creating data sources to embed them in pages