notion-api Skill (intellectronica): Notion REST API

Teaches Claude to read and edit your Notion pages, databases and comments through the Notion REST API with curl and jq.

Installs: 98.1K; on skills.sh
Stars: 299; on GitHub
Files: 4; besides SKILL.md
Updated: Apr 2026; last repo commit

notion-api gives Claude the Notion REST API rules: authentication, headers, endpoints, pagination, rate limits and errors. It calls Notion with curl and jq, or small scripts. It covers search, pages, blocks, databases, data sources, users and comments.

It needs a Notion integration token in the NOTION_API_TOKEN environment variable, or one you paste in. The SKILL.md says to confirm with you before updates, deletes, schema changes, batches and multi-page creates, and never to print the token.

Good for

People who want Claude to read and update Notion without an MCP server
Developers scripting against Notion databases
Teams who want a confirmation step before bulk edits

Install notion-api

Claude Code

Copy this prompt.

Install the notion-api skill in Claude Code. Run this command:

claude plugin marketplace add intellectronica/agent-skills
claude plugin install notion-api@intellectronica-skills

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Both routes are in the README and install only notion-api. The plugin contains the SKILL.md and its 4 reference files and no hooks or MCP config. Pick one route, not both. Then set NOTION_API_TOKEN to a Notion integration token.

From the project README. Source.

What's in the skill

When it loads

This skill provides comprehensive instructions for interacting with the Notion API via REST calls. This skill should be used whenever the user asks to interact with Notion, including reading, creating, updating, or deleting pages, databases, blocks, comments, or any other Notion content. The skill covers authentication, all available endpoints, pagination, error handling, and best practices.

Sections in SKILL.md

Authentication
API Key Handling
Request Headers
Verifying Authentication
Base URL and Conventions
Rate Limits
Request Size Limits
Confirmation for Destructive Operations
Core API Endpoints
Search
Pages
Blocks (Page Content)
Databases
Data Sources (API v2025-09-03+)
Users
Comments

Key facts

Author: intellectronica (repo owner)
Repo: intellectronica/agent-skills
Installs on skills.sh: 98,110
Repo stars: 299
License: CC0-1.0
Last repo commit: 2026-04-25
Files in the skill folder: 5 files including SKILL.md
Needs: NOTION_API_TOKEN (Notion integration token)
API version header: Notion-Version: 2025-09-03

What it includes

NOTION_API_TOKEN, or a key you provide, or Claude asks
Never displayed or logged, and used only in the Authorization header. Verified with GET /v1/users/me.
Network · Authentication
POST /v1/search for pages and data sources
Filter and sort by last edited time.
Network · Search
Retrieve, create, update and archive pages
Archive sets archived to true. Page properties are separate from content.
Delete · Pages
Retrieve, append, update and delete page content
Page content is read with block children.
Delete · Blocks
Retrieve, query, create and update
Query uses filters and sorts.
Write · Databases
Create and manage data sources (API 2025-09-03)
New in API version 2025-09-03; pages can be created under a data source.
Write · Data Sources
List users, retrieve one, or retrieve the bot user
Used to test the token.
Network · Users
Retrieve and create comments
Read comments on a page or block and add new ones.
Write · Comments
has_more cursors, 3 requests per second, size limits
Retry with exponential backoff on HTTP 429.
Pagination and limits
Ask before updates, deletes, schema changes and bulk work
One confirmation can cover a group of related operations.
Confirmation for destructive operations
block-types, property-types, filters-and-sorts, rich-text
Four deep-dive files, 5 files in the folder with SKILL.md.
references/

From the official docs

Permissions

Medium risk

With your Notion token, Claude can read, edit and archive any page the integration can reach. Share only the pages it needs with the integration, and keep its confirmation step on.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can edit and archive Notion content
The endpoints include create, update, delete and archive for pages, blocks and databases. The SKILL.md says to ask you first, so do not turn confirmations off for bulk work. github.com
Your token is used in shell commands
Claude puts the token in curl headers. Use an integration that only has access to the pages it needs, and avoid pasting the token into chat. github.com

Technical details

Talks to	api.notion.com
Sign-in and keys	Reads NOTION_API_TOKEN from the environment or a key you give Claude. The SKILL.md says never to display, log or send it anywhere except the Authorization header.
Scopes	Notion integration token (pages shared with the integration)

Questions

What does the notion-api skill do?

It teaches Claude to use the Notion REST API directly with curl and jq: search, read, create, update and archive pages, query databases, edit blocks and write comments.

Do I need an API token?

Yes. Set NOTION_API_TOKEN in your environment, or give Claude a key. If neither exists, Claude asks you. The token is a Notion integration token, and the integration only sees pages shared with it.

Will it edit Notion without asking?

The SKILL.md says to ask for confirmation before updates, deletes, schema changes, batch creates and bulk operations. A single confirmation can cover a group of related steps.

Which API version does it use?

Notion-Version 2025-09-03, set in the request headers, including the data source endpoints.

How is it different from the Notion MCP server?

The SKILL.md never mentions MCP. This skill makes Claude call the REST API with curl and your integration token, so there is no server to run. Notion's MCP server is a separate product (our note, not the skill's).

How do I install it?

Use the install box above. The intellectronica/agent-skills README documents the skills CLI and a Claude Code plugin route, and both install only this skill.

Is it safe to install?

It bundles no scripts, but it makes Claude run curl commands with your Notion token that can edit and archive content. Share only the pages it needs with the integration.

Information

updated Nov 2, 2026

Repository: intellectronica/agent-skills
Folder: skills/notion-api

intellectronica/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

agent-skills README · github.com
agent-skills marketplace.json · github.com
notion-api SKILL.md · github.com
notion-api references/block-types.md · github.com
notion-api references/filters-and-sorts.md · github.com