notion

Notion

Use the Notion API to search, create, read, and update pages, databases, and blocks.

Setup Guide

Before using this skill, you need to create a Notion integration and grant it access to your pages:

1. Create an Integration

1. Go to https://www.notion.com/my-integrations
2. Click "New integration"
3. Name your integration (e.g., "Byaan")
4. Select the workspace you want to connect
5. Set capabilities: enable Read content, Update content, and Insert content as needed
6. Click Submit to create the integration
7. Copy the Internal Integration Secret (starts with ntn_ or secret_)
8. Paste this key in Settings > Skills > Notion in the app

2. Grant Access to Pages

This step is required — integrations can only see pages explicitly shared with them.

1. Open the Notion page or database you want to access
2. Click the "..." menu in the top-right corner
3. Click "Connections" (or "Add connections")
4. Find and select your integration by name
5. Repeat for each page/database you want to access

How Authentication Works

You do not need to handle authentication manually. When you call execute_skill_api(), the system automatically:

1. Retrieves the API key from the configured credentials
2. Adds the Authorization: Bearer <api_key> header
3. Adds the Notion-Version: 2022-06-28 header

Just call the API with skill name, endpoint path, method, and body — authentication is handled for you.

Finding Pages and Content

When a user asks to find, read, or work with a Notion page, ALWAYS start with a search. Never assume you know the page ID.

Search Workflow

1. Search by title to find pages:

POST /search
{"query": "Meeting Notes"}

1. Filter to pages only (exclude databases):

POST /search
{
  "query": "Meeting Notes",
  "filter": {"property": "object", "value": "page"}
}

1. Get recently edited pages:

POST /search
{
  "query": "",
  "sort": {"direction": "descending", "timestamp": "last_edited_time"}
}