notion-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

本Skill支持通过Notion REST API与Notion工作区进行交互。可使用

curl

和

jq

进行直接REST调用，或根据任务需求编写临时脚本。

Authentication

认证

API Key Handling

API密钥管理

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.

环境变量：检查环境中是否存在
```
NOTION_API_TOKEN
```
用户提供的密钥：如果用户在上下文提供了API密钥，则使用该密钥
无可用密钥：如果两者都不可用，使用AskUserQuestion（或类似功能）向用户请求API密钥

重要提示：除了在

Authorization

头中使用外，绝不要显示、记录或发送

NOTION_API_TOKEN

。仅确认其是否存在，缺失时向用户请求，在请求中使用——但绝不要回显或暴露它。

Request Headers

请求头

All requests require these headers:

bash

-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json"

所有请求都需要以下请求头：

bash

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

bash

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

通过获取机器人用户信息来测试API密钥：

bash

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

基础URL与约定

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

基础URL：
```
https://api.notion.com
```
API版本：
```
2025-09-03
```
（必填请求头）
数据格式：所有请求/响应体均为JSON
ID：UUIDv4格式（请求中可省略连字符）
时间戳：ISO 8601格式（
```
2020-08-12T02:12:33.231Z
```
）
属性名称：
```
snake_case
```
空值：使用
```
null
```
而非空字符串

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

平均速率：每个集成每秒3次请求
突发速率：允许短暂超过此限制的突发请求
速率限制响应：HTTP 429状态码，包含
```
Retry-After
```
请求头
应对策略：收到429响应时实现指数退避

Request Size Limits

请求大小限制

Type	Limit
Maximum block elements per payload	1000
Maximum payload size	500KB
Rich text content	2000 characters
URLs	2000 characters
Equations	1000 characters
Email addresses	200 characters
Phone numbers	200 characters
Multi-select options	100 items
Relations	100 related pages
People mentions	100 users
Block arrays per request	100 elements

类型	限制
每个负载中的最大区块元素数	1000
最大负载大小	500KB
富文本内容	2000字符
URL	2000字符
公式	1000字符
邮箱地址	200字符
电话号码	200字符
多选选项	100项
关联	100个关联页面
提及用户	100个用户
每个请求中的区块数组	100个元素

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

核心API端点

Search

搜索

Search across all accessible pages and databases:

bash

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"

"data_source"

(or omit for both)

搜索所有可访问的页面和数据库：

bash

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

过滤值：

"page"

或

"data_source"

（或省略以包含两者）

页面

Retrieve a Page

获取页面

bash

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.

bash

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

注意：此接口返回页面属性，而非内容。如需获取内容，请使用“获取子区块”接口并传入页面ID。

Create a Page

创建页面

bash

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+)

bash

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

父级选项：

```
{"page_id": "..."}
```
- 在页面下创建
```
{"database_id": "..."}
```
- 在数据库中创建（旧版）
```
{"data_source_id": "..."}
```
- 在数据源中创建（API v2025-09-03+）

Update a Page

更新页面

bash

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

bash

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

其他更新选项：

cover

、

is_locked

、

in_trash

Archive (Delete) a Page

归档（删除）页面

bash

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

bash

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:

bash

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

对于包含超过25个引用的属性：

bash

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

获取子区块

bash

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.

bash

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

传入页面ID作为

block_id

即可获取页面内容。检查每个区块的

has_children

字段以判断是否有嵌套内容。

Append Block Children

添加子区块

bash

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

bash

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

每个请求最多可添加100个区块，支持最多2级嵌套。

请求体中的位置选项：

默认：追加到末尾
```
"position": {"type": "start"}
```
- 插入到开头

"position": {"type": "after_block", "after_block": {"id": "block-id"}}

- 插入到指定区块之后

Retrieve a Block

获取区块

bash

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

bash

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

更新区块

bash

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.

bash

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

更新操作会替换指定字段的整个值。

Delete a Block

删除区块

bash

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).

bash

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

将区块移至回收站（可恢复）。

Databases

数据库

Retrieve a Database

获取数据库

bash

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.

bash

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

返回数据库结构，包括数据源和属性。

Query a Database

查询数据库

bash

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.

bash

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

有关过滤和排序的详细文档，请参阅

references/filters-and-sorts.md

。

Create a Database

创建数据库

bash

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

bash

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

更新数据库

bash

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

bash

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+)

数据源（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.

数据源是数据库中的独立表格。从API版本2025-09-03开始，数据库可包含多个数据源。

Create a Data Source

创建数据源

bash

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

bash

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

列出所有用户

bash

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

bash

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

获取用户

bash

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

bash

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)

获取机器人用户（自身）

bash

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

bash

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

获取评论

bash

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.

bash

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

传入页面ID作为

block_id

即可获取页面级评论。

Create a Comment

创建评论

On a page:

bash

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:

bash

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.

在页面上创建评论：

bash

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

回复讨论：

bash

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

注意：API无法启动新的内联讨论线程，也无法编辑或删除现有评论。

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:

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

Example request with cursor:

json

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

支持分页的端点会返回：

```
has_more
```
：布尔值，表示是否还有更多结果
```
next_cursor
```
：下一页的游标
```
results
```
：结果数组

遍历所有结果的步骤：

发起初始请求（省略
```
start_cursor
```
）
检查响应中的
```
has_more
```
如果为
```
true
```
，提取
```
next_cursor
```
并将其作为
```
start_cursor
```
包含在下一次请求中
重复直到
```
has_more
```
为
```
false
```

带游标的请求示例：

json

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

Error Handling

错误处理

HTTP Status	Code	Description
400	`invalid_json`	Request body is not valid JSON
400	`invalid_request_url`	URL is malformed
400	`invalid_request`	Request is not supported
400	`validation_error`	Request body doesn't match expected schema
400	`missing_version`	Missing Notion-Version header
401	`unauthorized`	Invalid bearer token
403	`restricted_resource`	Token lacks permission
404	`object_not_found`	Resource doesn't exist or not shared with integration
409	`conflict_error`	Data collision during transaction
429	`rate_limited`	Rate limit exceeded (check Retry-After header)
500	`internal_server_error`	Unexpected server error
503	`service_unavailable`	Notion unavailable or 60s timeout exceeded
503	`database_connection_unavailable`	Database unresponsive
504	`gateway_timeout`	Request timeout

HTTP状态码	错误码	描述
400	`invalid_json`	请求体不是有效的JSON
400	`invalid_request_url`	URL格式错误
400	`invalid_request`	请求不被支持
400	`validation_error`	请求体不符合预期的 schema
400	`missing_version`	缺少Notion-Version请求头
401	`unauthorized`	无效的Bearer令牌
403	`restricted_resource`	令牌缺少权限
404	`object_not_found`	资源不存在或未与集成共享
409	`conflict_error`	事务期间数据冲突
429	`rate_limited`	超出速率限制（检查Retry-After请求头）
500	`internal_server_error`	意外的服务器错误
503	`service_unavailable`	Notion不可用或超过60秒超时
503	`database_connection_unavailable`	数据库无响应
504	`gateway_timeout`	请求超时

Best Practices

最佳实践

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

存储ID：创建页面/数据库时，存储返回的ID以便后续更新
使用属性ID：通过ID引用属性而非名称，以确保稳定性
批量操作：将多个小操作合并为更少的请求
遵守速率限制：收到429响应时实现指数退避
检查
has_more
：列表端点始终要处理分页
更新前验证：在进行更新前获取当前状态
使用环境变量：绝不要硬编码API密钥
优雅处理错误：检查响应状态码和错误消息
Schema大小：保持数据库Schema大小在50KB以下以获得最佳性能
属性限制：包含超过25个页面引用的属性需要单独获取

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

有关特定主题的详细文档，请参阅：

```
references/block-types.md
```
- 所有支持的区块类型及其结构
```
references/property-types.md
```
- 数据库属性类型和值格式
```
references/filters-and-sorts.md
```
- 数据库查询过滤和排序语法
```
references/rich-text.md
```
- 富文本对象结构和注解

notion-api

Original

Translation

Notion API Skill

Notion API Skill

Authentication

认证

API Key Handling

API密钥管理

Request Headers

请求头

Verifying Authentication

验证认证

Base URL and Conventions

基础URL与约定

Rate Limits

速率限制

Request Size Limits

请求大小限制

Confirmation for Destructive Operations

破坏性操作确认

Core API Endpoints

核心API端点

Search

搜索

Pages

页面

Retrieve a Page

获取页面

Create a Page

创建页面

Update a Page

更新页面

Archive (Delete) a Page

归档（删除）页面

Retrieve a Page Property Item

获取页面属性项

Blocks (Page Content)

区块（页面内容）

Retrieve Block Children

获取子区块

Append Block Children

添加子区块

Retrieve a Block

获取区块

Update a Block

更新区块

Delete a Block

删除区块

Databases

数据库

Retrieve a Database

获取数据库

Query a Database

查询数据库

Create a Database

创建数据库

Update a Database

更新数据库

Data Sources (API v2025-09-03+)

数据源（API v2025-09-03+）

Create a Data Source

创建数据源

Users

用户

List All Users

列出所有用户

Retrieve a User

获取用户

Retrieve Bot User (Self)

获取机器人用户（自身）

Comments

评论

Retrieve Comments

获取评论

Create a Comment

创建评论

Pagination

分页

Error Handling