OpenParable
Skip to content
← Back to skills

Better Notion

Apps & Automation
better-notion

Better Notion is an Agent Skill for apps & automation published in the CraftOS-dev/CraftBot repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Full CRUD for Notion pages, databases, and blocks. Create, read, update, delete, search, and query.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/CraftOS-dev/CraftBot/blob/HEAD/skills/better-notion/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/better-notion, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Notion

Use the Notion API for pages, data sources (databases), and blocks.

Setup

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

Share target pages/databases with your integration in Notion UI.

API Basics

NOTION_KEY=$(cat ~/.config/notion/api_key)
curl -X POST "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

Common Operations

# Search
curl -X POST "https://api.notion.com/v1/search" -d '{"query": "title"}'

# Get page
curl "https://api.notion.com/v1/pages/{page_id}"

# Get page blocks
curl "https://api.notion.com/v1/blocks/{page_id}/children"

# Create page in database
curl -X POST "https://api.notion.com/v1/pages" -d '{
  "parent": {"data_source_id": "xxx"},
  "properties": {"Name": {"title": [{"text": {"content": "Item"}}]}}
}'

# Query database
curl -X POST "https://api.notion.com/v1/data_sources/{id}/query" -d '{
  "filter": {"property": "Status", "select": {"equals": "Active"}}
}'

# Update page
curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" -d '{
  "properties": {"Status": {"select": {"name": "Done"}}}
}'

# Add blocks
curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" -d '{
  "children": [{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Text"}}]}}]
}'

# Delete page or block (moves to trash)
curl -X DELETE "https://api.notion.com/v1/blocks/{block_id}"

# Restore from trash (set archived to false)
curl -X PATCH "https://api.notion.com/v1/blocks/{block_id}" -d '{"archived": false}'

Property Types

TypeFormat
Title{"title": [{"text": {"content": "..."}}]}
Text{"rich_text": [{"text": {"content": "..."}}]}
Select{"select": {"name": "Option"}}
Multi-select{"multi_select": [{"name": "A"}]}
Date{"date": {"start": "2024-01-15"}}
Checkbox{"checkbox": true}
Number{"number": 42}
URL{"url": "https://..."}

2025-09-03 API Notes

  • Databases = "data sources" in API
  • Use data_source_id for both creating pages and querying
  • Get data_source_id from search results (the id field)
  • Rate limit: ~3 req/sec