notion-api

Kỹ năng này cung cấp hướng dẫn toàn diện để tương tác với Notion API thông qua các lệnh gọi REST. Kỹ năng này nên được sử dụng bất cứ khi nào người dùng yêu cầu tương tác với Notion, bao gồm đọc, tạo, cập nhật hoặc xóa các trang, cơ sở dữ liệu, khối, bình luận hoặc bất kỳ nội dung Notion nào khác. Kỹ năng bao gồm xác thực, tất cả các điểm cuối có sẵn, phân trang, xử lý lỗi và các phương pháp hay nhất.

npx skills add https://github.com/intellectronica/agent-skills --skill notion-api

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:

-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

  • 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
  • Empty Values: Use null instead of empty strings

Rate Limits

  • Average: 3 requests per second per integration
  • Bursts: Brief bursts above this limit are allowed
  • Rate Limited Response: HTTP 429 with Retry-After header
  • Strategy: Implement exponential backoff when receiving 429 responses

Request Size Limits

TypeLimit
Maximum block elements per payload1000
Maximum payload size500KB
Rich text content2000 characters
URLs2000 characters
Equations1000 characters
Email addresses200 characters
Phone numbers200 characters
Multi-select options100 items
Relations100 related pages
People mentions100 users
Block arrays per request100 elements

Confirmation for Destructive Operations

IMPORTANT: Before executing any operation that modifies or deletes data, ask the user for confirmation. This includes:

  • Updating pages or blocks
  • Deleting/archiving pages or blocks
  • Modifying database schemas
  • Creating pages (if multiple or in batch)
  • Any bulk operations

For a logical group of related operations, a single confirmation is sufficient.

Core API Endpoints

Search

Search across all accessible pages and databases:

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "search term",
    "filter": {"property": "object", "value": "page"},
    "sort": {"direction": "descending", "timestamp": "last_edited_time"},
    "page_size": 100
  }' | jq

Filter values: "page" or "data_source" (or omit for both)

Pages

Retrieve a Page

curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Note: This returns page properties, not content. For content, use "Retrieve block children" with the page ID.

Create a Page

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "properties": {
      "title": {
        "title": [{"text": {"content": "Page Title"}}]
      }
    },
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Paragraph content"}}]
        }
      }
    ]
  }' | jq

Parent options:

  • {"page_id": "..."} - Create under a page
  • {"database_id": "..."} - Create in a database (legacy)
  • {"data_source_id": "..."} - Create in a data source (API v2025-09-03+)

Update a Page

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "title": {"title": [{"text": {"content": "Updated Title"}}]}
    },
    "icon": {"type": "emoji", "emoji": "📝"},
    "archived": false
  }' | jq

Additional update options: cover, is_locked, in_trash

Archive (Delete) a Page

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}' | jq

Retrieve a Page Property Item

For properties with more than 25 references:

curl -s "https://api.notion.com/v1/pages/{page_id}/properties/{property_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Blocks (Page Content)

Retrieve Block Children

curl -s "https://api.notion.com/v1/blocks/{block_id}/children?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Use the page ID as block_id to get page content. Check has_children on each block for nested content.

Append Block Children

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}/children" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {
          "rich_text": [{"type": "text", "text": {"content": "New Section"}}]
        }
      },
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Content here"}}]
        }
      }
    ]
  }' | jq

Maximum 100 blocks per request, up to 2 levels of nesting.

Position options in request body:

  • Default: appends to end
  • "position": {"type": "start"} - Insert at beginning
  • "position": {"type": "after_block", "after_block": {"id": "block-id"}} - Insert after specific block

Retrieve a Block

curl -s "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Update a Block

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "paragraph": {
      "rich_text": [{"type": "text", "text": {"content": "Updated content"}}]
    }
  }' | jq

The update replaces the entire value for the specified field.

Delete a Block

curl -s -X DELETE "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Moves block to trash (can be restored).

Databases

Retrieve a Database

curl -s "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Returns database structure including data sources and properties.

Query a Database

curl -s -X POST "https://api.notion.com/v1/databases/{database_id}/query" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "Status",
      "select": {"equals": "Done"}
    },
    "sorts": [
      {"property": "Created", "direction": "descending"}
    ],
    "page_size": 100
  }' | jq

See references/filters-and-sorts.md for comprehensive filter and sort documentation.

Create a Database

curl -s -X POST "https://api.notion.com/v1/databases" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "title": [{"type": "text", "text": {"content": "My Database"}}],
    "is_inline": true,
    "initial_data_source": {
      "properties": {
        "Name": {"title": {}},
        "Status": {
          "select": {
            "options": [
              {"name": "To Do", "color": "red"},
              {"name": "In Progress", "color": "yellow"},
              {"name": "Done", "color": "green"}
            ]
          }
        },
        "Due Date": {"date": {}}
      }
    }
  }' | jq

Update a Database

curl -s -X PATCH "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "title": [{"text": {"content": "Updated Title"}}],
    "description": [{"text": {"content": "Database description"}}]
  }' | jq

Data Sources (API v2025-09-03+)

Data sources are individual tables within a database. As of API version 2025-09-03, databases can contain multiple data sources.

Create a Data Source

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"type": "database_id", "database_id": "database-id"},
    "title": [{"type": "text", "text": {"content": "New Data Source"}}],
    "properties": {
      "Name": {"title": {}},
      "Description": {"rich_text": {}}
    }
  }' | jq

Users

List All Users

curl -s "https://api.notion.com/v1/users?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Retrieve a User

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

Retrieve Bot User (Self)

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

Comments

Retrieve Comments

curl -s "https://api.notion.com/v1/comments?block_id={block_id}&page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Use a page ID as block_id for page-level comments.

Create a Comment

On a page:

curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "page-id"},
    "rich_text": [{"type": "text", "text": {"content": "Comment content"}}]
  }' | jq

Reply to a discussion:

curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "discussion_id": "discussion-id",
    "rich_text": [{"type": "text", "text": {"content": "Reply content"}}]
  }' | jq

Note: The API cannot start new inline discussion threads or edit/delete existing comments.

Pagination

Paginated endpoints return:

  • has_more: Boolean indicating more results exist
  • next_cursor: Cursor for the next page
  • results: Array of items

To iterate through all results:

  1. Make the initial request (omit start_cursor)
  2. Check has_more in the response
  3. If true, extract next_cursor and include it as start_cursor in the next request
  4. Repeat until has_more is false

Example request with cursor:

{
  "page_size": 100,
  "start_cursor": "v1%7C..."
}

Error Handling

HTTP StatusCodeDescription
400invalid_jsonRequest body is not valid JSON
400invalid_request_urlURL is malformed
400invalid_requestRequest is not supported
400validation_errorRequest body doesn't match expected schema
400missing_versionMissing Notion-Version header
401unauthorizedInvalid bearer token
403restricted_resourceToken lacks permission
404object_not_foundResource doesn't exist or not shared with integration
409conflict_errorData collision during transaction
429rate_limitedRate limit exceeded (check Retry-After header)
500internal_server_errorUnexpected server error
503service_unavailableNotion unavailable or 60s timeout exceeded
503database_connection_unavailableDatabase unresponsive
504gateway_timeoutRequest timeout

Best Practices

  1. Store IDs: When creating pages/databases, store the returned IDs for future updates
  2. Use Property IDs: Reference properties by ID rather than name for stability
  3. Batch Operations: Aggregate multiple small operations into fewer requests
  4. Respect Rate Limits: Implement exponential backoff for 429 responses
  5. Check has_more: Always handle pagination for list endpoints
  6. Validate Before Updates: Retrieve current state before making updates
  7. Use Environment Variables: Never hardcode API keys
  8. Handle Errors Gracefully: Check response status codes and error messages
  9. Schema Size: Keep database schemas under 50KB for optimal performance
  10. Properties Limit: Properties with >25 page references require separate retrieval

References

For detailed documentation on specific topics, see:

  • references/block-types.md - All supported block types and their structures
  • references/property-types.md - Database property types and value formats
  • references/filters-and-sorts.md - Database query filter and sort syntax
  • references/rich-text.md - Rich text object structure and annotations

Skills liên quan

neon
neondatabase
Tổng quan về nền tảng Neon dành cho ứng dụng và tác nhân, bao gồm Postgres, Auth, Data API, và các dịch vụ mới: Object Storage, Compute Functions, và AI Gateway. Sử dụng bất cứ khi nào "Neon" được đề cập để có cái nhìn tổng quan về cách làm việc với Neon và cách bắt đầu. Nếu không, các khả năng riêng lẻ là các kích hoạt: "object storage" hoặc "S3-compatible storage", "serverless functions", "background jobs", hoặc "run code near my database", "AI gateway", "LLM proxy", "model routing", hoặc "call an LLM" →...
apidevelopmentdatabase
neon-realtime
neondatabase
Neon Realtime makes any SQL query live. Build realtime, reactive apps and agents on Lakebase Postgres with live SQL queries and reactivity primitives. Use when app UI or agent state must update live from database rows (dashboards, feeds, collaboration, multi-user or multi-device sync), for optimistic mutations, or to replace polling or other realtime sync systems. Triggers include "live query", "subscribe", "sync engine", "useLiveQuery", "TanStack DB", "optimistic updates", "@neon/realtime"....
apidevelopmentdatabase
convex-setup-auth
get-convex
Thiết lập xác thực Convex, ánh xạ danh tính và kiểm soát truy cập. Sử dụng cho đăng nhập, nhà cung cấp xác thực, bảng người dùng, hàm được bảo vệ hoặc vai trò trong ứng dụng Convex.
developmentdatabaseapi
extension-querying-oql
caffeinelabs
Quick reference for the Caffeine Data Intelligence agent to query an OQL-exposing canister (schema() + execute()) through the `icp` CLI against the project's `backend` canister: read the schema, form JSON queries (filter / order / paginate / aggregate / dotted-path edges), and parse the Candid result rows.
developmentdatabaseapi
lark-base
larksuite
当需要用 lark-cli 操作飞书多维表格(Base)时调用:搜索 Base、建表、字段管理、记录读写、记录分享链接、视图配置、历史查询,以及角色/表单/仪表盘管理/工作流;也适用于把旧的 +table / +field / +record 写法改成当前命令写法。涉及字段设计、公式字段、查找引用、跨表计算、行级派生指标、数据分析需求时也必须使用本 skill。
data-analysisapidatabase
airunway-aks-setup
microsoft
Thiết lập AI Runway trên AKS — từ cụm trống đến mô hình đang chạy. Bao gồm xác minh cụm, cài đặt bộ điều khiển, đánh giá GPU, thiết lập nhà cung cấp và bước đầu tiên…
devopsapiaws
appinsights-instrumentation
microsoft
Hướng dẫn và tài liệu tham khảo để tích hợp công cụ đo lường cho ứng dụng web với Azure Application Insights. Bao gồm thiết lập SDK, các mẫu telemetry và cấu hình cho ứng dụng ASP.NET Core và Node.js được lưu trữ trên Azure. Phân biệt giữa kỹ năng này (tham khảo và hướng dẫn) và azure-prepare (triển khai thực tế); gọi azure-prepare khi người dùng muốn thêm công cụ đo lường vào dự án của họ. Cung cấp hướng dẫn tự động tích hợp công cụ đo lường cho ứng dụng C# ASP.NET Core trong Azure App Service, cùng với hướng dẫn thủ công...
devopsapidevelopment
azure-ai
microsoft
Truy cập các dịch vụ Azure AI Search, Speech, OpenAI và Document Intelligence thông qua các công cụ MCP thống nhất. AI Search hỗ trợ tìm kiếm toàn văn, vector, kết hợp và ngữ nghĩa với tính năng tăng cường AI tích hợp để trích xuất thực thể và OCR. Dịch vụ Speech xử lý chuyển đổi giọng nói thành văn bản theo thời gian thực và hàng loạt, tổng hợp văn bản thành giọng nói với giọng neural và phân biệt người nói. Các công cụ MCP cung cấp quyền truy cập trực tiếp: azure__search cho truy vấn chỉ mục và azure__speech cho phiên âm và tổng hợp SDK...
researchapidevelopment