byaan-ai/byaan/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"}
}

1. Get all accessible pages (empty query):

POST /search
{"query": ""}

1. Read page content once you have the page_id:

GET /blocks/{page_id}/children

Search Parameters

Search Behavior

• Search only returns pages/databases explicitly shared with the integration
• Search matches titles only, not page content
• To search within page content, fetch blocks first then search locally
• Archived pages won't appear in search results
• Page titles are in properties.title, not a simple title field

Common Operations

Get a Page

GET /pages/{page_id}

Get Page Content (Blocks)

GET /blocks/{page_id}/children

Create a Page in a Database

POST /pages
{
  "parent": {"database_id": "xxx"},
  "properties": {
    "Name": {"title": [{"text": {"content": "New Item"}}]},
    "Status": {"select": {"name": "Todo"}}
  }
}

Create a Standalone Page

POST /pages
{
  "parent": {"page_id": "parent_page_id"},
  "properties": {
    "title": {"title": [{"text": {"content": "Page Title"}}]}
  },
  "children": [
    {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Content here"}}]}}
  ]
}

Query a Database

POST /databases/{database_id}/query
{
  "filter": {"property": "Status", "select": {"equals": "Active"}},
  "sorts": [{"property": "Date", "direction": "descending"}]
}

Get Database Schema

GET /databases/{database_id}

Create a Database

POST /databases
{
  "parent": {"page_id": "xxx"},
  "title": [{"text": {"content": "My Database"}}],
  "properties": {
    "Name": {"title": {}},
    "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
    "Date": {"date": {}}
  }
}

Update Page Properties

PATCH /pages/{page_id}
{"properties": {"Status": {"select": {"name": "Done"}}}}

Add Blocks to a Page

PATCH /blocks/{page_id}/children
{
  "children": [
    {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello"}}]}}
  ]
}

Delete a Block

DELETE /blocks/{block_id}

Property Types

Common property formats for database items:

Pagination

All list endpoints support pagination:

• `page_size`: Number of results per request (default and max: 100)
• `start_cursor`: Cursor from previous response to get next page

Response includes:

• `has_more`: true if more results exist
• `next_cursor`: Use as start_cursor in next request

Example pagination flow:

POST /databases/{id}/query
{"page_size": 100}
 
# If response has "has_more": true
POST /databases/{id}/query
{"page_size": 100, "start_cursor": "next_cursor_value"}

Common Pitfalls

1. "Object not found" errors: The integration hasn't been granted access to that page. Go to the page in Notion → "..." → "Connections" → add your integration.

1. Search returns empty results: Search only finds pages explicitly shared with the integration, not all pages in the workspace.

1. Can't find page content: GET /pages/{id} returns metadata only. Use GET /blocks/{id}/children to get the actual content.

1. Database rows are pages: Items in a Notion database are actually pages with parent.type: "database_id". Query the database, then fetch each row's blocks if you need content.

1. Page IDs from URLs: Notion URLs contain the page ID at the end (32 hex chars). Convert abc123def456... to UUID format abc123de-f456-... or use without dashes — both work.

1. Rich text arrays: Text properties are always arrays of rich text objects, even for simple strings: [{"text": {"content": "Hello"}}]

Notes

• Page/database IDs are UUIDs (with or without dashes)
• The API cannot set database view filters — that's UI-only
• Rate limit: ~3 requests/second average
• Use is_inline: true when creating databases to embed them in pages