Notion API免费3年，用户用它造出了什么狠东西

2021年5月，Notion（一款笔记与项目管理工具）开放了应用程序接口（API）的公测。个人用户完全免费，所有付费计划都包含在内。三年过去，这个看似"开发者专属"的功能，已经被普通用户玩出了花——有人用它自动生成每日站会文档，有人把邮件里的潜在客户直接写进数据库，还有人把Dev.to（一个开发者内容平台）的文章同步到内容日历。

但大多数人甚至不知道这个功能存在。

这不是你的问题。Notion的产品设计出了名的"克制"，API入口藏得比某些手机的开发者选项还深。今天这篇，我们直接上代码，看看这个免费工具到底能干什么，以及为什么它可能是你被低估的效率杠杆。

第一步：拿到你的"钥匙"

任何API调用都需要认证。Notion用的是Bearer Token（令牌认证），获取方式比想象中简单：进入Notion设置 → 集成 → 新建集成 → 复制Token。不需要信用卡，不需要企业邮箱，个人账号直接开搞。

代码层面，你只需要这几行：

TOKEN = "your_notion_api_key"

HEADERS = {

"Authorization": f"Bearer {TOKEN}",

"Content-Type": "application/json",

"Notion-Version": "2022-06-28"

注意那个Notion-Version字段。这是2022年6月的版本号，至今仍是主流。Notion的API迭代不算快，但足够稳定——对于不想频繁改代码的用户来说，这是好消息。

查询数据库：比筛选器灵活10倍

Notion原生的筛选器已经很强，但API查询能做到它做不到的事：跨数据库关联、条件组合、自动化触发。

比如这段代码，查询某个数据库里所有Status（状态）为"Done"（已完成）的条目：

def query_database(db_id, filter_obj=None):

data = {}

if filter_obj:

data["filter"] = filter_obj

r = requests.post(f"https://api.notion.com/v1/databases/{db_id}/query",

headers=HEADERS, json=data)

results = r.json()["results"]

return [{"id": p["id"], "props": {k: v for k, v in p["properties"].items()}}

for p in results]

items = query_database("your_db_id", {

"property": "Status",

"status": {"equals": "Done"}

返回的是结构化数据，你可以直接丢给Pandas做分析，或者发给Slack机器人。原生筛选器做不到这种"数据出口"的自由。

创建页面：把重复劳动交给代码

每天手动创建站会文档？从邮件复制客户信息到CRM（客户关系管理系统）？这些重复动作都可以用create_page函数解决。

def create_page(db_id, title, status="Not started"):

data = {

"parent": {"database_id": db_id},

"properties": {

"Name": {"title": [{"text": {"content": title}}]},

"Status": {"status": {"name": status}}

r = requests.post("https://api.notion.com/v1/pages",

headers=HEADERS, json=data)

return r.json()["id"]

page_id = create_page("db_id", "New task from Python")

关键点在于properties字段的构造。Notion的属性类型有title（标题）、status（状态）、select（单选）、multi_select（多选）、date（日期）等十几种，每种在API里的JSON结构都不一样。官方文档有完整对照表，但说实话，第一次对接时你可能会骂娘——这种"灵活性"的代价就是学习曲线。

但一旦跑通，你就拥有了一个可编程的笔记系统。

批量写入内容：从数据到可读文档

创建空白页面只是开始。add_blocks函数让你能往页面里塞标题、段落、列表、代码块，甚至嵌入其他页面。

def add_blocks(page_id, blocks):

r = requests.patch(f"https://api.notion.com/v1/blocks/{page_id}/children",

headers=HEADERS, json={"children": blocks})

return r.json()

add_blocks(page_id, [

{"type": "heading_2", "heading_2": {

"rich_text": [{"text": {"content": "Summary"}}]

}},

{"type": "paragraph", "paragraph": {

"rich_text": [{"text": {"content": "This was created via the API."}}]

}},

{"type": "bulleted_list_item", "bulleted_list_item": {

"rich_text": [{"text": {"content": "First point"}}]

注意type和对应字段的命名一致性。heading_2、paragraph、bulleted_list_item都是块类型，每种有自己的结构要求。这种设计让Notion的页面本质上是一个JSON树，你可以用代码任意组装。

一个实际场景：你的爬虫抓了一批数据，想自动生成分析报告。用add_blocks可以批量插入图表标题、数据摘要、待办事项，甚至用divider（分隔线）做视觉分区。全程不需要打开Notion客户端。

真实自动化场景：从玩具到生产工具

官方文档列了几个典型用例，我们逐个拆解可行性：

每日站会机器人：用定时任务（如GitHub Actions或服务器cron）每天早上创建页面，预填模板。比手动复制粘贴省3-5分钟/天，一年就是15-20小时。适合远程团队。

CRM自动录入：监听邮件或表单提交，解析内容后调用create_page。难点在于字段映射——客户邮件里的"公司名"可能出现在正文、签名或附件，需要写点正则或上自然语言处理（NLP）。

内容日历同步：Dev.to有官方API，可以定时拉取文章列表，对比Notion数据库的已有条目，增量同步。适合多平台分发的内容运营者。

项目数据看板：聚合多个数据库的数据，用Python生成图表，再以图片形式写回Notion。或者更轻量：直接生成Markdown表格，用add_blocks插入。

会议笔记自动化：对接日历API（如Google Calendar），读取参会人和议程，会前自动创建页面并@相关人。Notion的mention功能在API里也有对应字段。

限制与反直觉的设计

Notion API的限速是每秒3请求，没有日限额。对于个人自动化场景，这个额度够用；但如果你要做大规模数据迁移，得自己实现分页和重试逻辑。

分页参数是固定的100条/页。查询大型数据库时，代码里要处理has_more和next_cursor字段。这是REST API的标准做法，但Notion的文档在这个细节上写得不够醒目，新手容易踩坑。

另一个反直觉的点：API创建的页面不会触发Notion的原生通知。如果你指望用机器人@同事来提醒他们看新文档，得配合Slack或邮件做二次通知。这不是bug，是设计选择——Notion把"通知"视为产品层面的功能，而非数据层面的。

换句话说，API是后台管道，不是前台喇叭。

为什么这值得你现在动手

Notion的商业模式很清晰：个人免费，团队付费。API对个人完全开放，意味着你可以零成本搭建一套"个人数据中台"——笔记、任务、知识库全部可编程，不需要买Zapier（一款自动化工具）的付费计划，不需要学复杂的集成平台。

对比其他产品的API策略：Roam Research（另一款笔记工具）的API至今还是付费功能；Obsidian（本地优先的笔记工具）依赖社区插件，没有官方API；飞书文档的API对企业友好，但个人开发者门槛更高。

Notion的选择是"普惠式开放"，这在2021年算激进，现在看是聪明——它培养了一大批基于Notion的第三方工具生态，从网页剪藏到数据可视化，这些工具反过来增加了用户粘性。