Notion Api

The notion-api skill provides comprehensive instructions for developers and automation users to interact with Notion workspaces through REST API calls, covering authentication, all available endpoints, pagination, error handling, and best practices. It solves the problem of programmatically reading, creating, updating, and deleting Notion content by offering detailed guidance on proper API key handling, request formatting, rate limiting, and confirmation protocols for destructive operations. The skill is designed for developers building integrations, agents, or scripts that need reliable, secure access to Notion data.

skills.sh installs: 102.5K
GitHub stars: 301
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add intellectronica/agent-skills --skill notion-api --agent claude-code

Installs into .claude/skills of the current project.

Files

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

Environment Variable: Check if NOTION_API_TOKEN is available in the environment
User-Provided Key: If the user provides an API key in context, use that instead
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:

-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:

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

SKILL.md on GitHub

Details

Repository: github.com/intellectronica/agent-skills
Categories: Backend & APIs, Security, AI & Agent Building, Debugging, Office & Documents