home / skills / openclaw / skills / notion-api

notion-api skill

unsafe

This skill provides a lightweight Node-based Notion API CLI to search, query databases, and create pages without exposing secrets.

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

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

Files (3)

SKILL.md

1.4 KB

---
name: notion-api
description: Generic Notion API CLI (Node) for search, querying data sources (databases), and creating pages. Configure with NOTION_KEY (or ~/.config/notion/api_key).
---

# notion-api (generic)

This skill provides a small Node-based CLI for the Notion API. It’s designed to be shareable: **no hard-coded database IDs and no secrets in the repo**.

## Auth

Provide a Notion integration token via either:

- `NOTION_KEY` env var, or
- `~/.config/notion/api_key` (first line)

Also make sure the target pages/databases are shared with your integration in Notion.

## Commands (CLI)

Run via:

- `node scripts/notion-api.mjs <command> ...`

### Search

```bash
node scripts/notion-api.mjs search "query" --page-size 10
```

### Query a data source (database query)

```bash
node scripts/notion-api.mjs query --data-source-id <DATA_SOURCE_ID> --page-size 10
# optionally pass raw JSON body:
node scripts/notion-api.mjs query --data-source-id <ID> --body '{"filter": {...}, "sorts": [...], "page_size": 10}'
```

### Create a page in a database

```bash
node scripts/notion-api.mjs create-page --database-id <DATABASE_ID> --title "My item" --title-prop Name
```

## Output

All commands print JSON to stdout.

## Notes

- Notion API version header defaults to `2025-09-03` (override with `NOTION_VERSION`).
- Rate limits apply; prefer `page_size` and minimal calls.

Overview

This skill is a lightweight Node-based CLI for interacting with the Notion API to search, query databases, and create pages. It requires no hard-coded database IDs or secrets in the project and uses environment configuration for authentication. Commands return JSON to stdout so you can pipe or store results easily. It is intended for quick automation, backups, and simple integration scripts.

How this skill works

Authenticate by setting NOTION_KEY or placing an API key in ~/.config/notion/api_key (first line). The CLI exposes commands to search, query a database (with optional raw JSON body), and create pages in a database. All requests include a Notion API version header (default 2025-09-03) and respect Notion rate limits; responses are printed as JSON to stdout.

When to use it

Quickly search a Notion workspace from scripts or CI
Query a Notion database for automated reports or exports
Create items in a Notion database from other tools or webhooks
Integrate Notion data into backup or archival pipelines
Prototype automations without embedding secrets in code

Best practices

Provide credentials via NOTION_KEY or ~/.config/notion/api_key, never commit secrets
Share target databases/pages with your Notion integration before calling commands
Use page_size to limit results and reduce rate limit pressure
When performing complex filters or sorts, pass a raw JSON body to the query command
Override NOTION_VERSION only when you need a specific API feature and understand compatibility

Example use cases

Search for blocks, pages, or databases matching a query string from the command line
Run a nightly job that queries a database and exports results to JSON for archival
Create a new database item from a CI job after successful deployment
Combine query output with other tools (jq, scripts) to build custom reports
Batch migrate or sync small datasets into Notion without hard-coding IDs

FAQ

How do I authenticate?

Set NOTION_KEY in the environment or put your token in ~/.config/notion/api_key (first line).

Can I pass complex query filters?

Yes. Use the query command with --body and provide a raw JSON object containing filter, sorts, and page_size.

Where do results go?

All commands print JSON to stdout so you can redirect or pipe the output.