playbooks

home / skills / openclaw / skills / better-notion

better-notion skill

/skills/tyler6204/better-notion

This skill helps you manage Notion pages, databases, and blocks with full CRUD operations, improving automation and data organization.

npx playbooks add skill openclaw/skills --skill better-notion

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.4 KB
---
name: better-notion
description: Full CRUD for Notion pages, databases, and blocks. Create, read, update, delete, search, and query.
metadata: {"clawdbot":{"emoji":"📝"}}
---

# Notion

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

## Setup

```bash
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

```bash
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

```bash
# 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

| Type | Format |
|------|--------|
| 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

Overview

This skill provides full CRUD operations for Notion pages, databases (data sources), and blocks using the Notion API. It enables create, read, update, delete, search, and query workflows, plus block manipulation and restore-from-trash support. The integration expects a stored API key and shared access to target pages or databases in your Notion workspace.

How this skill works

The skill issues authenticated HTTP requests to Notion endpoints (pages, blocks, data_sources, and search) using the 2025-09-03 API version. It supports creating pages in a database by supplying data_source_id, reading pages and block children, patching properties or blocks, querying databases with filters, and deleting or restoring items. Rate limiting is respected; typical practical limit is about 3 requests per second.

When to use it

  • Automate creating and updating Notion pages from external systems.
  • Back up Notion content or export structured data from databases.
  • Build integrations that search or query Notion programmatically.
  • Manage page content at block level (add paragraphs, lists, headings).
  • Restore or archive content as part of audit or retention workflows.

Best practices

  • Store the Notion API key securely (e.g., ~/.config/notion/api_key) and never hard-code it in source control.
  • Share target pages and databases with the integration so the API has access to them.
  • Use data_source_id (not database id text) when creating pages or querying databases; obtain it from search results.
  • Respect rate limits (roughly 3 requests/sec); batch operations when possible and add retries with exponential backoff.
  • Validate property payload shapes for each property type (title, rich_text, select, multi_select, date, checkbox, number, url).

Example use cases

  • Create a new task row in a Notion database with title, status select, due date, and assignee.
  • Query a projects database for items where Status equals "Active" and export to CSV for reporting.
  • Programmatically add a paragraph and checklist blocks to a page when onboarding a new project.
  • Archive pages by deleting (trash) and restore them later by PATCHing archived:false.
  • Search a workspace for pages matching a title keyword and batch-update a custom property.

FAQ

How do I authenticate requests?

Store your integration key and send it as Authorization: Bearer <key> with Notion-Version: 2025-09-03 and Content-Type: application/json.

How do I create a page inside a database?

POST to /v1/pages with parent.data_source_id set to the database id and include properties following the Notion property formats (e.g., Title uses title array).