A reliable and robust command-line automation skill for keeping external data sources (CSV, JSON, REST APIs) in perfect sync with your Notion databases.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install sync-data-notion
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install sync-data-notion using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Sync Data to Notion?
The sync-data-notion skill provides seamless, bidirectional data synchronization between external sources—such as local CSV files, JSON payloads, or live REST APIs—and Notion databases. Built to go far beyond simple one-shot imports, this tool manages consistency, conflict detection, incremental updates, and partial failures automatically. It ensures that your Notion integrations stay healthy, reliable, and error-free without manual intervention.
As part of the Openclaw Skills ecosystem, it leverages strict schema validation, mapping external data properties directly to equivalent Notion property types like title, rich_text, select, and date. By utilizing robust rate-limiting recovery and detailed execution reporting, this utility delivers production-ready reliability for developers and automated workflows.
Sync Data to Notion Use Cases
- Syncing CSV/JSON Files: Push local database exports, inventory tables, or user logs directly into a Notion database dynamically.
- Automating API Integrations: Keep a Notion workspace continuously updated with live records pulled from external REST endpoints on a recurring schedule.
- Performing Risk-Free Previews: Utilize dry-run mode to preview incoming data modifications, additions, and deletions without changing production data.
- Notion-to-External Backup (Reverse Sync): Export updated database pages from Notion back to your master external systems or data warehouses.
- Incremental Sync Runs: Optimize performance and API quota usage by syncing only records modified since the last recorded execution timestamp.
How Sync Data to Notion Works
- Source Parsing and Validation: The skill reads your source data (CSV, JSON, or REST API endpoint) and checks for physical errors or missing fields.
- Schema Retrieval: It calls the Notion API to retrieve the target database schema, ensuring property types (like numbers, dates, and multi-selects) align perfectly with incoming payloads.
- Field Mapping: Displays a clear mapping table detailing how source fields align with Notion database properties before running.
- Conflict Check: It queries the active Notion database to build a localized key-to-page lookup map to detect existing records.
- Record Mutation: Runs creations (
POST) and updates (PATCH) over the target records, serialize-writing pages, and automatically handling Notion's rate limits (429) using exponential backoff. - Verification & Summary: Queries written pages to verify success and outputs a comprehensive JSON execution report outlining created, updated, skipped, and failed records.
Sync Data to Notion Setup
Configure your environment and run the sync using the terminal. Ensure you have your NOTION_API_KEY ready as an environment variable.
# Export your Notion API Key
export NOTION_API_KEY="your_integration_token_here"
# Run a dry-run sync to preview changes without making database updates
/sync-data-notion --dry-run --source data.csv --database-id "your_notion_db_id"
# Run a full bidirectional sync
/sync-data-notion --full --source data.json --database-id "your_notion_db_id"
# Execute an incremental sync based on the last recorded run
/sync-data-notion --incremental --source https://api.example.com/items --database-id "your_notion_db_id"
Sync Data to Notion Data Schema & Taxonomy
This skill maps external schemas cleanly to Notion property structures and tracks execution metadata. Below is the taxonomy used during mapping:
| Source Field Type | Notion Property Type | Write Pattern / Validation |
|---|---|---|
| String / ID | title |
Sent as a standard title array (Required) |
| Text / String | rich_text |
Converted to a rich_text text object array |
| Number / Float | number |
Strictly validated as float or null; rejects string inputs |
| Boolean | checkbox |
Boolean value (true/false) |
| Single Category | select |
Formatted as a select object: {\"name\": \"value\"} |
| Multi-tag Array | multi_select |
Array of select name objects: [{\"name\": \"tag1\"}, {\"name\": \"tag2\"}] |
| ISO8601 Date | date |
Formatted as {\"date\": {\"start\": \"YYYY-MM-DD\"}} |
| URL / Email | url / email |
String validation format |
Sync History State
To track incremental runs, state files are written to:
~/.sync_notion_last_run/{database_id}.json containing {\"last_sync_timestamp\": \"ISO8601_STRING\"}.
Sync Data to Notion Advanced Features
- Dry-Run Previewing: Fully preview record additions, updates, and deletes with high precision without modifying active Notion records.
- Stateful Incremental Syncing: Read state logs to sync only modified records, reducing Notion API consumption and speeding up cron-based workflows.
- Smart Rate-Limit Backoff: Automatically handles 429 errors by parsing the
Retry-Afterheader and performing up to three retries with exponential backoff. - Comprehensive Execution Reporting: Generates structured JSON reports containing exact record actions and structured error details for debugging sync conflicts.
- Reverse Synchronization: Easily export production-edited Notion database rows back to localized external files or REST APIs via the
--reversemode.
SKILL.md
Loading
Related Openclaw Skills
rednote-creator
An end-to-end Xiaohongshu content creation and automated publishing skill for high-engagement social media management.
Convert GitHub Repository
A versatile skill designed to transform GitHub repository structures, code, issues, PRs, and metadata into cleanly formatted Markdown, JSON, CSV, or tree representations.
Car Specs Crawler
A pythonic data extraction skill designed to scrape comprehensive car configuration and technical specifications from top tier Chinese automotive web platforms.
opencli-exec Alias
A backward-compatible alias and routing layer designed to map legacy workspace memory commands to the canonical opencli tool.
AO Op
An OpenClaw skill that provides a reliable wrapper to operate a local installation of Agent Orchestrator (AO) directly through execution commands.
dashscope-imagegen
An advanced image generation skill powered by Alibaba Cloud's DashScope wan2.6-t2i (通义万相) model for creating high-quality visual assets.
Featured*
