Notion API Skill Guide

What This Skill Does

The Notion skill empowers you to interact with your Notion workspace directly through the OpenClaw AI agent. It leverages the official Notion API to perform a variety of operations, including creating, reading, updating, and deleting pages, databases (referred to as data sources in the API), and individual blocks within pages. This skill is ideal for automating repetitive tasks, managing information efficiently, and integrating your Notion content with other workflows.

Key functionalities include:

• Searching for existing pages and data sources.
• Retrieving detailed information about specific pages.
• Extracting the content (blocks) of any page.
• Creating new pages, with options to set properties like titles and statuses.
• Querying data sources (databases) based on specific filters and sorting criteria.
• Creating new data sources (databases) with predefined properties.
• Updating existing page properties.

Installation

To install the Notion skill, you will need to configure your Notion API key and then use the OpenClaw installation command:

1. Obtain Notion API Key:

   • Go to https://www.notion.so/my-integrations.
   • Create a new integration or use an existing one.
   • Copy the generated API key (it typically starts with ntn_ or secret_).

2. Securely Store API Key:

   • Create a configuration directory if it doesn't exist: mkdir -p ~/.config/notion
   • Store your API key in a file: echo "YOUR_API_KEY_HERE" > ~/.config/notion/api_key (Replace YOUR_API_KEY_HERE with your actual key).

3. Share with Integration:

   • In your Notion workspace, navigate to the page or database you want the integration to access.
   • Click the "..." menu in the top-right corner.
   • Select "Connect to" and choose your integration's name.

4. **Install the Skill via OpenClaw:

clawhub install openclaw/openclaw/skills/notion

Use Cases

This skill opens up numerous possibilities for enhancing your productivity and workflow:

• Task Management: Automatically create new tasks in a Notion database from emails or messages, and update their status as they progress.
• Content Curation: Gather information from various sources and automatically structure it into new pages or database entries within Notion.
• Meeting Notes: Generate meeting summaries and save them as new pages in a dedicated meeting notes database.
• Project Tracking: Create new project pages, assign tasks, and track progress by updating database properties.
• Knowledge Base Management: Quickly add new entries, articles, or FAQs to your Notion-based knowledge base.
• Data Synchronization: Use Notion as a backend for other applications, automatically updating entries based on external events.

Example Prompts

Here are some examples of how you might interact with the Notion skill:

1. "Create a new page in my 'Projects' database titled 'Website Redesign' with the status set to 'Planning'."
2. "Find all pages in my workspace that contain the word 'report' and were modified in the last week."
3. "Add a new to-do item to my 'Daily Tasks' database with the title 'Call the client' and set the due date to tomorrow."

Tips & Limitations

Tips:

• API Version: The skill uses a specific Notion API version (2025-09-03). Ensure compatibility if Notion updates their API. The header Notion-Version is crucial for all requests.
• Database vs. Data Source: Remember that in the Notion API, "databases" are referred to as "data sources."
• Permissions: Ensure your integration has the necessary permissions to access and modify the specific pages and databases you intend to work with.
• Error Handling: While the skill handles basic operations, complex Notion API errors might require manual inspection and adjustment of the request payload or permissions.
• Block Types: When creating or updating blocks, familiarize yourself with the various block types supported by the Notion API (e.g., text, headings, to-do lists, images) and their corresponding JSON structures.

Limitations:

• API Rate Limits: Be mindful of Notion's API rate limits to avoid getting temporarily blocked. Avoid making excessive requests in a short period.
• Complex Structure: Creating highly complex nested pages or intricate database structures might be challenging and require detailed payload construction.
• Real-time Sync: The skill operates based on discrete API calls. It does not provide real-time synchronization of your entire Notion workspace.
• File Uploads: Direct file uploads to Notion might be complex and depend on specific API endpoints and authentication methods not explicitly detailed here.
• Requires Setup: The skill requires manual setup of the API key and sharing permissions within your Notion account before it can be used effectively.