介绍
# Notion
通过托管的 OAuth 身份验证访问 Notion API。查询数据库、创建页面、管理块以及搜索您的工作区。
## 快速开始
```bash # Search for pages 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 ```
## Base URL
``` https://gateway.maton.ai/notion/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 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`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取 API 密钥
1. 登录或在 [maton.ai](https://maton.ai) 创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Notion OAuth 连接。
### 列出连接
```bash 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 ```
### 创建连接
```bash 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 ```
### 获取连接
```bash 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 ```
**响应：** ```json { "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", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash 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` 请求头指定要使用的连接：
```bash 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 ```
如果省略，网关将使用默认（最早）的活动连接。
## 核心概念：数据库 (Databases) 与数据源
在 API 版本 2025-09-03 中，数据库和数据源是分开的：
| 概念 | 用于 | |---------|---------| | **数据库** | 创建数据库、获取数据源 ID | | **数据源** | 查询、更新架构、更新属性 |
使用 `GET /databases/{id}` 获取 `data_sources` 数组，然后使用 `/data_sources/` 端点：
```json { "object": "database", "id": "abc123", "data_sources": [ {"id": "def456", "name": "My Database"} ] } ```
## API 参考
### 搜索
搜索页面：
```bash POST /notion/v1/search Content-Type: application/json Notion-Version: 2025-09-03
{ "query": "meeting notes", "filter": {"property": "object", "value": "page"} } ```
搜索数据源：
```bash POST /notion/v1/search Content-Type: application/json Notion-Version: 2025-09-03
{ "filter": {"property": "object", "value": "data_source"} } ```
### 数据源
#### 获取数据源
```bash GET /notion/v1/data_sources/{dataSourceId} Notion-Version: 2025-09-03 ```
#### 查询数据源
```bash POST /notion/v1/data_sources/{dataSourceId}/query Content-Type: application/json Notion-Version: 2025-09-03
{ "filter": { "property": "Status", "select": {"equals": "Active"} }, "sorts": [ {"property": "Created", "direction": "descending"} ], "page_size": 100 } ```
#### 更新数据源
```bash PATCH /notion/v1/data_sources/{dataSourceId} Content-Type: application/json Notion-Version: 2025-09-03
{ "title": [{"type": "text", "text": {"content": "Updated Title"}}], "properties": { "NewColumn": {"rich_text": {}} } } ```
### 数据库
#### 获取数据库
```bash GET /notion/v1/databases/{databaseId} Notion-Version: 2025-09-03 ```
#### 创建数据库
```bash 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": "New Database"}}], "properties": { "Name": {"title": {}}, "Status": {"select": {"options": [{"name": "Active"}, {"name": "Done"}]}} } } ```
### 页面
#### 获取页面
```bash GET /notion/v1/pages/{pageId} Notion-Version: 2025-09-03 ```
#### 创建页面
```bash 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"}}]} } } ```
#### 在数据源中创建页面
```bash 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"}} } } ```
#### 更新页面属性
```bash PATCH /notion/v1/pages/{pageId} Content-Type: application/json Notion-Version: 2025-09-03
{ "properties": { "Status": {"select": {"name": "Done"}} } } ```
#### 更新页面图标
```bash PATCH /notion/v1/pages/{pageId} Content-Type: application/json Notion-Version: 2025-09-03
{ "icon": {"type": "emoji", "emoji": "🚀"} } ```
#### 归档页面
```bash PATCH /notion/v1/pages/{pageId} Content-Type: application/json Notion-Version: 2025-09-03
{ "archived": true } ```
### 块
#### 获取子块
```bash GET /notion/v1/blocks/{blockId}/children Notion-Version: 2025-09-03 ```
#### 追加子块
```bash 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"}}] } } ] } ```
#### 删除块
```bash DELETE /notion/v1/blocks/{blockId} Notion-Version: 2025-09-03 ```
### 用户
#### 列出用户
```bash GET /notion/v1/users Notion-Version: 2025-09-03 ```
#### 获取当前用户
```bash GET /notion/v1/users/me Notion-Version: 2025-09-03 ```
## 筛选运算符
- `equals`, `does_not_equal` - `contains`, `does_not_contain` - `starts_with`, `ends_with` - `is_empty`, `is_not_empty` - `greater_than`, `less_than`
## 块类型
- `paragraph`, `heading_1`, `heading_2`, `heading_3` - `bulleted_list_item`, `numbered_list_item` - `to_do`, `code`, `quote`, `divider`
## 代码示例
### JavaScript
```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
```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` 以禁用 glob 解析 - 重要：当将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，`$MATON_API_KEY` 等环境变量可能无法正确展开。通过管道传输时，您可能会收到“Invalid API key”错误。
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Notion 连接 | | 401 | Maton API 密钥无效或缺失 | | 429 | 请求频率受限（每账户每秒 10 次请求） | | 4xx/5xx | 来自 Notion API 的透传错误 |
### 故障排除：API 密钥问题
1. 检查是否设置了 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash 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 简介](https://developers.notion.com/reference/intro) - [搜索](https://developers.notion.com/reference/post-search.md) - [查询数据库](https://developers.notion.com/reference/post-database-query.md) - [获取页面](https://developers.notion.com/reference/retrieve-a-page.md) - [创建页面](https://developers.notion.com/reference/post-page.md) - [更新页面](https://developers.notion.com/reference/patch-page.md) - [追加子块](https://developers.notion.com/reference/patch-block-children.md) - [筛选参考](https://developers.notion.com/reference/post-database-query-filter.md) - [LLM 参考](https://developers.notion.com/llms.txt) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])