notion-api by intellectronica/agent-skills
npx skills add https://github.com/intellectronica/agent-skills --skill notion-api此技能支持通过 Notion REST API 与 Notion 工作区进行交互。可直接使用 curl 和 jq 进行 REST 调用,或根据任务需要编写临时脚本。
NOTION_API_TOKEN重要提示:切勿在任何地方显示、记录或发送 NOTION_API_TOKEN,除非在 Authorization 请求头中。确认其存在,若缺失则询问,在请求中使用它——但切勿回显或暴露它。
所有请求都需要以下请求头:
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json"
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
通过获取机器人用户信息来测试 API 密钥:
curl -s "https://api.notion.com/v1/users/me" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" | jq
https://api.notion.com2025-09-03(必需请求头)2020-08-12T02:12:33.231Z)snake_casenull 而非空字符串Retry-After 请求头| 类型 | 限制 |
|---|---|
| 每个有效载荷的最大块元素数 | 1000 |
| 最大有效载荷大小 | 500KB |
| 富文本内容 | 2000 个字符 |
| URL | 2000 个字符 |
| 公式 | 1000 个字符 |
| 电子邮件地址 | 200 个字符 |
| 电话号码 | 200 个字符 |
| 多选选项 | 100 项 |
| 关联关系 | 100 个相关页面 |
| 人员提及 | 100 个用户 |
| 每个请求的块数组 | 100 个元素 |
重要提示:在执行任何修改或删除数据的操作之前,请向用户请求确认。这包括:
对于一组逻辑上相关的操作,一次确认即可。
在所有可访问的页面和数据库中搜索:
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"(或省略以包含两者)
curl -s "https://api.notion.com/v1/pages/{page_id}" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" | jq
注意:此操作返回页面属性,而非内容。要获取内容,请使用页面 ID 调用"检索块子项"。
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+)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
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
对于引用超过 25 个页面的属性:
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
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 以获取嵌套内容。
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"}} - 插入到特定块之后curl -s "https://api.notion.com/v1/blocks/{block_id}" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" | jq
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
此更新会替换指定字段的整个值。
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
将块移至回收站(可恢复)。
curl -s "https://api.notion.com/v1/databases/{database_id}" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" | jq
返回数据库结构,包括数据源和属性。
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。
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
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
数据源是数据库内的独立表格。自 API 版本 2025-09-03 起,数据库可以包含多个数据源。
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
curl -s "https://api.notion.com/v1/users?page_size=100" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" | jq
curl -s "https://api.notion.com/v1/users/{user_id}" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" | jq
curl -s "https://api.notion.com/v1/users/me" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" | jq
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 来获取页面级别的评论。
在页面上:
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
回复讨论:
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 无法启动新的内联讨论线程,也无法编辑/删除现有评论。
支持分页的端点返回:
has_more:布尔值,指示是否存在更多结果next_cursor:用于获取下一页的光标results:项目数组要遍历所有结果:
start_cursor)has_moretrue,提取 next_cursor 并将其作为 start_cursor 包含在下一个请求中has_more 为 false带光标的请求示例:
{
"page_size": 100,
"start_cursor": "v1%7C..."
}
| HTTP 状态码 | 代码 | 描述 |
|---|---|---|
| 400 | invalid_json | 请求正文不是有效的 JSON |
| 400 | invalid_request_url | URL 格式错误 |
| 400 | invalid_request | 请求不受支持 |
| 400 | validation_error | 请求正文与预期模式不匹配 |
| 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 | 请求超时 |
has_more:始终处理列表端点的分页有关特定主题的详细文档,请参阅:
references/block-types.md - 所有支持的块类型及其结构references/property-types.md - 数据库属性类型和值格式references/filters-and-sorts.md - 数据库查询过滤器和排序语法references/rich-text.md - 富文本对象结构和注解每周安装量
4.4K
代码库
GitHub 星标数
228
首次出现
2026年1月28日
安全审计
安装于
opencode2.5K
codex2.5K
kimi-cli2.4K
cursor1.9K
gemini-cli1.9K
github-copilot1.8K
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.
NOTION_API_TOKEN is available in the environmentIMPORTANT : 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.
All requests require these headers:
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json"
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
https://api.notion.com2025-09-03 (required header)2020-08-12T02:12:33.231Z)snake_casenull instead of empty stringsRetry-After header| 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 |
IMPORTANT : Before executing any operation that modifies or deletes data, ask the user for confirmation. This includes:
For a logical group of related operations, a single confirmation is sufficient.
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)
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.
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+)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
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
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
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.
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:
"position": {"type": "start"} - Insert at beginning"position": {"type": "after_block", "after_block": {"id": "block-id"}} - Insert after specific blockcurl -s "https://api.notion.com/v1/blocks/{block_id}" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" | jq
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.
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).
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.
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.
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
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 are individual tables within a database. As of API version 2025-09-03, databases can contain multiple data sources.
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
curl -s "https://api.notion.com/v1/users?page_size=100" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" | jq
curl -s "https://api.notion.com/v1/users/{user_id}" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" | jq
curl -s "https://api.notion.com/v1/users/me" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" | jq
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.
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.
Paginated endpoints return:
has_more: Boolean indicating more results existnext_cursor: Cursor for the next pageresults: Array of itemsTo iterate through all results:
start_cursor)has_more in the responsetrue, extract next_cursor and include it as start_cursor in the next requesthas_more is falseExample request with cursor:
{
"page_size": 100,
"start_cursor": "v1%7C..."
}
| 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 |
has_more: Always handle pagination for list endpointsFor detailed documentation on specific topics, see:
references/block-types.md - All supported block types and their structuresreferences/property-types.md - Database property types and value formatsreferences/filters-and-sorts.md - Database query filter and sort syntaxreferences/rich-text.md - Rich text object structure and annotationsWeekly Installs
4.4K
Repository
GitHub Stars
228
First Seen
Jan 28, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykFail
Installed on
opencode2.5K
codex2.5K
kimi-cli2.4K
cursor1.9K
gemini-cli1.9K
github-copilot1.8K
97,600 周安装
| 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 |