Notion API

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.

302 stars 27 forksProductivity & Notes Plugin marketplace

Install

Claude Code plugin
/plugin marketplace add intellectronica/agent-skills

The repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add intellectronica/agent-skills --skill notion-api
Manual install
git clone --depth 1 https://github.com/intellectronica/agent-skills.git /tmp/agent-skills
mkdir -p ~/.claude/skills
cp -r /tmp/agent-skills/plugins/notion-api/skills ~/.claude/skills/notion-api

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Notion API Skill

This skill enables interaction with Notion workspaces through the Notion REST API. Use `curl` and `jq` for direct REST calls, or write ad-hoc scripts as appropriate for the task.

## Authentication

### API Key Handling

1. **Environment Variable**: Check if `NOTION_API_TOKEN` is available in the environment
2. **User-Provided Key**: If the user provides an API key in context, use that instead
3. **No Key Available**: If neither is available, use AskUserQuestion (or equivalent) to request the API key from the user

**IMPORTANT**: Never display, log, or send `NOTION_API_TOKEN` anywhere except in the `Authorization` header. Confirm its existence, ask if missing, use it in requests—but never echo or expose it.

### Request Headers

All requests require these headers:

```bash
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json"
```

### Verifying Authentication

Test the API key by retrieving the bot user:

```bash
curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq
```

## Base URL and Conventions

- **Base URL**: `https://api.notion.com`
- **API Version**: `2025-09-03` (required header)
- **Data Format**: JSON for all request/response bodies
- **IDs**: UUIDv4 format (dashes optional in requests)
- **Timestamps**: ISO 8601 format (`2020-08-12T02:12:33.231Z`)
- **Property Names**: `snake_case`
Read the full skill on GitHub

Details

Skill name
notion-api
Path
plugins/notion-api/skills/SKILL.md
License
CC0-1.0
Repo updated
25 April 2026

FAQ

What does the Notion API skill do?

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.

How do I install the Notion API skill?

Claude Code plugin: /plugin marketplace add intellectronica/agent-skills. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Notion API popular?

It lives in intellectronica/agent-skills, which has 302 GitHub stars and 27 forks.

Related skills

Beautiful Mermaid

302

intellectronica/agent-skills

Render Mermaid diagrams as SVG and PNG using the Beautiful Mermaid library. Use when the user asks to render a Mermaid diagram.

Software Development27

Gpt Image 1 5

302

intellectronica/agent-skills

Generate and edit images using OpenAI's GPT Image 1.5 model. Use when the user asks to generate, create, edit, modify, change, alter, or update images. Also use when user references an existing image file and asks to modify it in any way (e.g., "modify this image", "change the background", "replace X with Y"). Supports text-to-image generation and image editing with optional mask. DO NOT read the image file first - use this skill directly with the --input-image parameter.

Images, Video & Audio27

Anki Connect

302

intellectronica/agent-skills

This skill is for interacting with Anki through AnkiConnect, and should be used whenever a user asks to interact with Anki, including to read or modify decks, notes, cards, models, media, or sync operations.

Productivity & Notes27

Skill Forge Plan

189

AgriciDaniel/skill-forge

Architecture and design planning for new Claude Code skills. Guides through use case definition, complexity tier selection, sub-skill decomposition, and file structure planning. Use when user says "plan skill", "design skill", "skill architecture", or "skill planning".

Productivity & Notes44

Monologue Notes API

302

intellectronica/agent-skills

Use this skill when the user wants to read or search their Monologue notes through the Monologue Notes REST API. It covers authentication with the MONOLOGUE_API_KEY environment variable, safe token handling, listing notes, fetching a single note, pagination, filters, and error handling. The API is read-only and should be accessed with direct HTTP requests such as curl or any equivalent REST client.

Productivity & Notes27

Todoist API

302

intellectronica/agent-skills

This skill provides instructions for interacting with Todoist using the td CLI tool. It covers CRUD operations for tasks/projects/sections/labels/comments, and requires confirmation before destructive actions. Use this skill when the user wants to read, create, update, or delete Todoist data.

Productivity & Notes27

Browse the most popular Claude skills, all productivity & notes skills, or write your own with the skills generator.