Notion

通过托管的OAuth认证访问Notion API。查询数据库、创建页面、管理模块，并在工作区中进行搜索。

快速入门

# 搜索页面
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'query': 'meeting notes'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/notion/v1/search', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Notion-Version', '2025-09-03')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础URL

https://gateway.maton.ai/notion/{原生API路径}

替换{原生API路径}为实际的Notion API端点路径。网关将请求代理到api.notion.com并自动注入您的OAuth令牌。

必需请求头

所有Notion API请求都需要版本头：

Notion-Version: 2025-09-03

认证

所有请求都需要在Authorization头中包含Maton API密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的API密钥设置为MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

1. 登录或在以下网址创建账户maton.ai
2. 前往maton.ai/settings
3. 复制您的 API 密钥

连接管理

在以下网址管理您的 Notion OAuth 连接https://ctrl.maton.ai。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=notion&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'notion'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "notion",
    "method": "OAUTH2",
    "metadata": {}
  }
}

在浏览器中打开返回的url以完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个 Notion 连接，请使用Maton-Connection标头指定要使用的连接：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'query': 'meeting notes'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/notion/v1/search', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Notion-Version', '2025-09-03')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最早创建的）活跃连接。

核心概念：数据库与数据源

在 API 版本 2025-09-03 中，数据库和数据源是分开的：

概念	用途
数据库	创建数据库，获取数据源 ID
数据源	查询、更新架构、更新属性

使用GET /databases/{id}来获取data_sources数组，然后使用/data_sources/端点：

{
  "object": "database",
  "id": "abc123",
  "data_sources": [
    {"id": "def456", "name": "我的数据库"}
  ]
}

API 参考

搜索

搜索页面：

POST /notion/v1/search
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "query": "会议记录",
  "filter": {"property": "object", "value": "page"}
}

搜索数据源：

POST /notion/v1/search
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "filter": {"property": "object", "value": "data_source"}
}

数据源

获取数据源

GET /notion/v1/data_sources/{dataSourceId}
Notion-Version: 2025-09-03

查询数据源

POST /notion/v1/data_sources/{dataSourceId}/query
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "filter": {
    "property": "状态",
    "select": {"equals": "激活"}
  },
  "sorts": [
    {"property": "创建时间", "direction": "descending"}
  ],
  "page_size": 100
}

更新数据源

PATCH /notion/v1/data_sources/{dataSourceId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "title": [{"type": "text", "text": {"content": "更新后的标题"}}],
  "properties": {
    "新列": {"rich_text": {}}
  }
}

数据库

获取数据库

GET /notion/v1/databases/{databaseId}
Notion-Version: 2025-09-03

创建数据库

POST /notion/v1/databases
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "parent": {"type": "page_id", "page_id": "PARENT_PAGE_ID"},
  "title": [{"type": "text", "text": {"content": "新数据库"}}],
  "properties": {
    "名称": {"title": {}},
    "状态": {"select": {"options": [{"name": "激活"}, {"name": "完成"}]}}
  }
}

页面

获取页面

GET /notion/v1/pages/{pageId}
Notion-Version: 2025-09-03

创建页面

POST /notion/v1/pages
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "parent": {"page_id": "PARENT_PAGE_ID"},
  "properties": {
    "title": {"title": [{"text": {"content": "New Page"}}]}
  }
}

在数据源中创建页面

POST /notion/v1/pages
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "parent": {"data_source_id": "DATA_SOURCE_ID"},
  "properties": {
    "Name": {"title": [{"text": {"content": "New Page"}}]},
    "Status": {"select": {"name": "Active"}}
  }
}

更新页面属性

PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "properties": {
    "Status": {"select": {"name": "Done"}}
  }
}

更新页面图标

PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "icon": {"type": "emoji", "emoji": "🚀"}
}

归档页面

PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "archived": true
}

区块

获取子区块

GET /notion/v1/blocks/{blockId}/children
Notion-Version: 2025-09-03

追加子区块

PATCH /notion/v1/blocks/{blockId}/children
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [{"type": "text", "text": {"content": "New paragraph"}}]
      }
    }
  ]
}

删除区块

DELETE /notion/v1/blocks/{blockId}
Notion-Version: 2025-09-03

用户

列出用户

GET /notion/v1/users
Notion-Version: 2025-09-03

获取当前用户

GET /notion/v1/users/me
Notion-Version: 2025-09-03

筛选运算符

• 等于，不等于
• 包含，不包含
• 以...开头，以...结尾
• 为空，不为空
• 大于，小于

块类型

• 段落，标题_1,标题_2,标题_3
• 项目符号列表项,编号列表项
• 待办事项,代码,引用,分割线

代码示例

JavaScript

const response = await fetch('https://gateway.maton.ai/notion/v1/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
    'Notion-Version': '2025-09-03'
  },
  body: JSON.stringify({ query: 'meeting' })
});

Python

import os
import requests

response = requests.post(
    'https://gateway.maton.ai/notion/v1/search',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Notion-Version': '2025-09-03'
    },
    json={'query': 'meeting'}
)

备注

• 所有ID均为UUID（可带或不带连字符）
• 使用GET /databases/{id}来获取包含数据源ID的data_sources数组
• 创建数据库需要POST /databases端点
• 删除块会返回带有archived: true
• 的块重要提示：使用curl命令时，如果URL包含括号（fields[]、sort[]、records[]），请使用curl -g
• 以禁用通配符解析重要提示：当将curl输出通过管道传递给jq或其他命令时，像在某些Shell环境中可能无法正确展开。通过管道传输时，您可能会遇到“无效API密钥”错误。

错误处理

状态码	含义
400	缺少Notion连接
401	无效或缺少Maton API密钥
429	请求频率受限（每个账户每秒10次请求）
4xx/5xx	来自Notion API的透传错误

故障排除：API密钥问题

1. 请检查是否已设置MATON_API_KEY环境变量：

echo $MATON_API_KEY

1. 通过列出连接来验证API密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：无效的应用名称

1. 请确保您的URL路径以notion开头。例如：

• 正确示例：https://gateway.maton.ai/notion/v1/search
• 错误示例：https://gateway.maton.ai/v1/search

资源

• Notion API 简介
• 搜索
• 查询数据库
• 获取页面
• 创建页面
• 更新页面
• 追加块子项
• 过滤器参考
• LLM 参考
• Maton 社区
• Maton 支持

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。