---

name: notion_db description: > OpenClaw skill for programmatic creation and management of Notion databases, properties, and data entries via the Notion API. Enables agents to set up and interact with Notion databases without manual UI intervention. entry_point: tools.py tools:

• create_database
• add_database_items
• query_database
• update_database_item

---

Notion Database Management Skill

This skill provides four tools for working with Notion databases through the Notion REST API. It supports all common property types, bulk data insertion, query filtering, and item updates.

---

Authentication Setup

The skill reads your Notion API token from the environment.

Step 1 — Create a Notion Integration:

1. Go to https://www.notion.so/my-integrations
2. Click + New integration → give it a name → Submit.
3. Copy the Internal Integration Token (secret_...).

Step 2 — Share your page with the integration:

In Notion, open the parent page → Share → Invite → select your integration.

Step 3 — Set the environment variable:

# Option A: shell export
export NOTION_API_TOKEN=secret_abc123...

# Option B: .env file in the skill directory
echo "NOTION_API_TOKEN=secret_abc123..." > .env

Optional environment variables:

| Variable | Default | Description | |---|---|---| | NOTION_API_VERSION | 2022-06-28 | Notion API version header | | NOTION_MAX_RETRIES | 3 | Retries on 429 / 5xx errors | | NOTION_RETRY_BACKOFF | 1.5 | Exponential back-off multiplier (seconds) | | NOTION_LOG_LEVEL | INFO | Verbosity: DEBUG, INFO, WARNING, ERROR |

---

Tools Reference

create_database

Create a new Notion database as a child of a parent page.

Parameters:

| Name | Type | Required | Description | |---|---|---|---| | parent_page_id | str | ✅ | Notion page ID to create the database under | | title | str | ✅ | Display title for the database | | properties | list[dict] | ✅ | List of property definitions (see below) | | token | str | ❌ | Notion API token. Falls back to NOTION_API_TOKEN env var |

Returns: { "success": bool, "database_id": str, "message": str }

Property definition fields:

| Field | Type | Required | Notes | |---|---|---|---| | name | str | ✅ | Column name shown in Notion | | type | str | ✅ | See supported types table below | | format | str | For number | e.g. "dollar", "percent", "number" | | options | list | For select / multi_select | [{"name": "X", "color": "blue"}, ...] | | formula | str | For formula | Notion formula expression string | | relation_database_id | str | For relation | Target database ID |

Supported property types:

| type value | Notion API type | Notes | |---|---|---| | title | title | Exactly one required per database | | text | rich_text | Multi-line text | | number | number | Optional format field | | select | select | Predefined single-choice options | | multi_select | multi_select | Multi-choice options | | date | date | Supports start + end + timezone | | checkbox | checkbox | Boolean | | url | url | — | | email | email | — | | phone_number | phone_number | — | | formula | formula | Notion formula expression | | relation | relation | Requires relation_database_id |

Select option colors: default, gray, brown, orange, yellow, green, blue, purple, pink, red

Example:

from skill import create_database

result = create_database(
    parent_page_id="a1b2c3d4e5f6...",
    title="Daily Study Plan",
    properties=[
        {"name": "Task",     "type": "title"},
        {"name": "Date",     "type": "date"},
        {
            "name": "Subject", "type": "select",
            "options": [
                {"name": "SQL",     "color": "blue"},
                {"name": "Python",  "color": "green"},
                {"name": "PySpark", "color": "orange"},
            ],
        },
        {
            "name": "Time Block", "type": "select",
            "options": [
                {"name": "Block 1", "color": "gray"},
                {"name": "Block 2", "color": "brown"},
                {"name": "Block 3", "color": "orange"},
            ],
        },
        {"name": "Duration", "type": "number", "format": "number"},
        {"name": "Done",     "type": "checkbox"},
        {
            "name": "Today's Progress", "type": "formula",
            "formula": 'if(prop("Done"), "✅ Done", "⏳ Pending")',
        },
    ],
)
print(result["database_id"])

---

add_database_items

Bulk-insert rows into an existing database. The schema is auto-fetched; formula and other read-only properties are silently skipped.

Parameters:

| Name | Type | Required | Description | |---|---|---|---| | database_id | str | ✅ | Target database ID | | items | list[dict] | ✅ | List of row dicts | | token | str | ❌ | Notion API token. Falls back to NOTION_API_TOKEN env var |

Returns: { "success": bool, "success_count": int, "failure_count": int, "failures": list, "message": str }

Value conventions per property type:

| Property type | Expected Python value | |---|---| | title / text | str | | number | int or float | | select | str (option name) | | multi_select | str (comma-separated) or list[str] | | date | str (ISO 8601) or {"start": "...", "end": "...", "time_zone": "..."} | | checkbox | bool | | url / email / phone_number | str |

Example:

from skill import add_database_items

result = add_database_items(
    database_id="abc123...",
    items=[
        {
            "Task":       "Review SQL Joins",
            "Date":       {"start": "2026-02-20"},
            "Subject":    "SQL",
            "Time Block": "Block 1",
            "Duration":   60,
            "Done":       False,
        },
        {
            "Task":       "Python Data Structures",
            "Date":       {"start": "2026-02-21"},
            "Subject":    "Python",
            "Time Block": "Block 2",
            "Duration":   45,
            "Done":       False,
        },
    ],
)
print(result["message"])

---

query_database

Query a database with optional filters and sorts. All matching rows are returned across pages automatically (Notion pagination is handled internally).

Parameters:

| Name | Type | Required | Description | |---|---|---|---| | database_id | str | ✅ | Database to query | | filter | dict | ❌ | Notion filter object | | sorts | list[dict] | ❌ | Sort specifications | | page_size | int | ❌ | Rows per API call (max 100, default 100) | | token | str | ❌ | Notion API token. Falls back to NOTION_API_TOKEN env var |

Returns: { "success": bool, "count": int, "items": list[dict], "message": str }

Each item in items is a flattened dict: { "id": str, "url": str, "<property>": <value>, ... }

Filter examples:

# Single property filter
filter = {"property": "Done", "checkbox": {"equals": True}}

# Compound AND filter
filter = {
    "and": [
        {"property": "Subject", "select": {"equals": "SQL"}},
        {"property": "Done",    "checkbox": {"equals": False}},
    ]
}

# Date range filter
filter = {
    "property": "Date",
    "date": {"on_or_after": "2026-02-20"},
}

Sort example:

sorts = [{"property": "Date", "direction": "ascending"}]

Example:

from skill import query_database

result = query_database(
    database_id="abc123...",
    filter={"property": "Done", "checkbox": {"equals": False}},
    sorts=[{"property": "Date", "direction": "ascending"}],
)
for item in result["items"]:
    print(item["Task"], item["Date"])

---

update_database_item

Update one or more properties on an existing Notion page (database row).

Parameters:

| Name | Type | Required | Description | |---|---|---|---| | page_id | str | ✅ | ID of the page / row to update | | properties | dict | ✅ | Property name → new value (same conventions as add_database_items) | | database_id | str | ❌ | Parent database ID for schema lookup (auto-discovered if omitted) | | token | str | ❌ | Notion API token. Falls back to NOTION_API_TOKEN env var |

Returns: { "success": bool, "page_id": str, "message": str }

Example:

from skill import update_database_item

result = update_database_item(
    page_id="page_id_here...",
    properties={
        "Done":     True,
        "Duration": 90,
    },
)
print(result["message"])

---

Error Handling

All tool functions return a dict with "success": False on failure (never raise exceptions to the agent). The dict also includes:

| Key | Description | |---|---| | error | Notion API error code or "config_error", "invalid_input" | | message | Human-readable error description | | status_code | HTTP status code (for API errors) |

Common error codes:

| Code | Cause | |---|---| | config_error | NOTION_API_TOKEN not set | | unauthorized | Invalid or expired token | | object_not_found | Wrong page / database ID, or integration lacks access | | validation_error | Invalid property definition or data value | | rate_limited | Too many requests; skill auto-retries up to NOTION_MAX_RETRIES | | invalid_input | Bad property definition (e.g., missing formula expression) |

---

Full End-to-End Example

See examples/daily_study_plan.py for a complete script that:

1. Creates a "Daily Study Plan" database with all seven property types
2. Populates 30 days of study sessions (rotating subjects and time blocks)
3. Queries the database and prints the first 5 items

---

Installation

pip install -r requirements.txt

---

Project Structure

notion_db/
├── SKILL.md              ← This file (OpenClaw skill documentation)
├── tools.py              ← OpenClaw tool functions (primary entry point)
├── skill.py              ← Legacy entry point (imports from tools.py)
├── database_manager.py   ← High-level orchestration layer
├── notion_client.py      ← Low-level HTTP client (auth, retries)
├── property_builders.py  ← Build database schema property fragments
├── item_builders.py      ← Build page property value payloads
├── config.py             ← Environment variable configuration
├── models.py             ← Data models and exception types
├── __init__.py           ← Package exports
├── requirements.txt
├── .env.example
├── examples/
│   └── daily_study_plan.py
└── tests/
    ├── test_property_builders.py
    ├── test_item_builders.py
    └── test_notion_client.py