Guide · Agent skill

How to use the Notion API Access agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

This guide explains the Notion API Access agent skill, a packaged set of instructions that lets an AI agent read and change content in your Notion workspace. It is aimed at people who have never installed an agent skill before, and at people who keep notes, tasks or project trackers in Notion. By the end you will know what the skill does, how to install it, how to set up your Notion API key, and how to ask for work in plain language.

Notion API Accessspinabot/brigade · MIT Download the skill

Quick start

1Create an integration. Go to https://notion.so/my-integrations and create a new integration. Copy the API key it shows, which starts with ntn_ or secret_.
2Save the key. Create the folder ~/.config/notion and save the key to ~/.config/notion/api_key.
3Share your pages. In Notion, open each target page or database, click "...", choose "Connect to", and select your integration.
4Install the skill. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
5Ask in plain language. Name the page or database and say what you want changed, such as adding a row or updating a status.
6Review the result. Check the page in Notion to confirm the change, especially for updates that overwrite existing properties.

What the Notion skill lets the agent do

Once installed, the agent can work inside your Notion workspace. It can search for pages, read their content, add new pages and rows to databases, update properties such as status or dates, and append text blocks to a page.

The skill works by making direct web requests to Notion's official API. It uses an API key you provide, and it can only reach pages you have explicitly shared with your integration.

Search for pages and data sources (databases) by title
Read a page's properties and its content blocks
Create pages inside a database and query databases with filters and sorts
Update page properties, for example changing Status to Done
Append paragraph blocks to a page
Create new databases (data sources) inside a page

Install the Notion skill

Download the skill ZIP from this page and unzip it. To make it available to Claude Code for all your projects, place the unzipped folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.

If you use the Claude apps instead, upload the ZIP under Settings → Capabilities → Skills.

Personal install: ~/.claude/skills/
Project install: .claude/skills/ inside your project folder
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Create a Notion integration and save your API key

The skill needs its own Notion integration, which is what gives it a key. Create one at https://notion.so/my-integrations and copy the API key. Keys start with ntn_ or secret_.

Save the key to a file at ~/.config/notion/api_key. The skill reads the key from that file each time it runs. The source shows this setup:

Create an integration at https://notion.so/my-integrations
Copy the API key (it starts with ntn_ or secret_)
Store it in ~/.config/notion/api_key

mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key

A Notion integration can only see pages you share with it. Open each page or database the agent should use, click "...", choose "Connect to", and select your integration name.

If the agent cannot find a page you know exists, this sharing step is the first thing to check.

Share each top-level page or database you want the agent to reach
Sharing a parent page makes its content available as the skill's requests reach it through the API

Trigger the skill with natural requests

You do not need to type API commands. Ask for the outcome you want in plain language, and name the page or database involved so the agent can find it. The skill uses the Notion API for each request, so the target must be shared with your integration first.

Good requests say what to change and where. Vague requests such as "update my notes" give the agent less to work with.

"Search my Notion for the page titled Q3 roadmap and summarise it."
"Add a new row to my Tasks database called Write blog post, status Todo."
"In my Projects database, find active items and list them by date, newest first."
"Mark the task Renew domain as Done."
"Append a paragraph to the Meeting notes page saying the review moved to Friday."

Understand the 2025-09-03 API differences

The skill is written for Notion API version 2025-09-03. In this version, databases are called data sources in the API. Each database has both a database_id and a data_source_id. Use database_id when creating a page, and data_source_id when querying.

You will rarely need to handle these IDs yourself, but they explain error messages you may see.

Create pages with parent database_id
Query with POST /v1/data_sources/{data_source_id}/query
Find a data_source_id by searching for the database, or calling GET /v1/data_sources/{data_source_id}
Notion-Version: 2025-09-03 is a required header

Know the limits and what the skill cannot do

The API cannot set database view filters. Those can only be configured in the Notion interface. Requests are rate limited to about 3 per second on average, and a 429 rate_limited response includes a Retry-After value telling the agent how long to wait.

Appending is capped at 100 children per request, up to two levels of nesting, and payloads are limited to 1000 block elements and 500KB.

No database view filter changes through the API
About 3 requests per second on average
Up to 100 block children per append request
Up to 1000 block elements and 500KB per payload

What people use it for

Summarising a project page or meeting notes stored in Notion
Adding tasks to a Tasks database from a conversation
Querying an active-projects database and listing items by date
Updating status or date properties as work progresses
Appending dated log entries to a running notes page
Developers testing read and write calls against the Notion API

Frequently asked questions

How do I install the Notion agent skill?

Download the skill ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder for one project. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.

What does the Notion skill need to run?

It needs a Notion integration created at notion.so/my-integrations, a Notion API key starting with ntn_ or secret_ saved to ~/.config/notion/api_key, curl available in the shell, and the target pages or databases shared with the integration.

Is the Notion API Access skill free?

The skill is listed under the MIT licence. The source does not state any price, so check this page for current licence terms. Notion's own account and plan requirements are separate from the skill.

Can the agent delete my Notion pages?

The source describes creating, reading, updating and appending content, along with searching and querying. It does not describe a delete operation, but the agent can change pages you have shared, so review important content regularly.

Why can't the agent see my page?

The page or database must be shared with your integration. Open it in Notion, click "...", choose "Connect to", and select your integration name, then ask again.

What is the difference between this skill and other Notion tools?

This skill calls Notion's public API directly with a key you provide, and it only reaches shared pages. It cannot change database view filters, which the source says are UI-only. Pick a different tool if you need offline use or features outside the public API.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose this skill if you keep tasks, notes or trackers in Notion and want an agent to read, file and update them, or if you are a developer scripting Notion data. Skip it if you are uneasy giving an AI agent write access to a workspace, do not want to create an integration and manage an API key, or need offline use or Notion features outside the public API.

Download the skill