跳到主要内容

API

cflow 提供公开的 HTTP RESTful API,可以用脚本对笔记做增删改查、上传附件,适合备份、批量处理或与第三方工具集成。

准备​

  1. 在 设置 → 我的账号 → 访问 Token 创建一个 API Token,按需选择有效期、读写权限与允许访问的空间。
  2. 每个请求带上 Authorization: Bearer <你的Token> 请求头。

接口一览​

方法路径用途
POST/api/v1/memo创建笔记
GET/api/v1/memo笔记列表(分页)
GET/api/v1/memo/{memoId}笔记详情
PATCH/api/v1/memo/{memoId}修改笔记
POST/api/v1/resource/db/create为笔记创建 cflow 数据库附件
POST/api/v1/resource/db/exec/{resourceId}执行 SQL(整批一个事务)

所有接口返回 JSON。时间字段均为 Unix 秒级时间戳。

参数说明​

创建笔记 — POST /api/v1/memo​

Body 为 JSON 对象:

参数类型必填说明
contentstring必填正文,Markdown 语法
spaceIdstring选填目标空间 ID,不传或传空串为默认空间
titlestring选填标题
secretLvint选填私密等级:0 公开(默认)、1 私密
createdTsint选填创建时间(Unix 秒),不传为当前时间。用于导入历史数据

返回创建后的笔记对象,笔记 ID 在 MemoId 字段(注意大小写)。

笔记列表 — GET /api/v1/memo​

参数通过 URL query 传递,全部选填:

参数类型必填说明
limitint选填每页数量。不传则返回全部,分页时建议始终传
offsetint选填偏移量,配合 limit 翻页,从 0 开始
spaceIdstring选填单空间过滤(旧参数,与 spaceIds 同传时以 spaceIds 为准)

返回笔记对象数组。

笔记详情 — GET /api/v1/memo/{memoId}​

参数位置类型必填说明
memoIdpathint必填笔记 ID

修改笔记 — PATCH /api/v1/memo/{memoId}​

memoId(path,int,必填)之外,Body 为 JSON,所有字段选填,只更新传了的字段:

参数类型必填说明
contentstring选填新正文
titlestring选填标题
secretLvint选填0 公开、1 私密
pinnedbool选填是否置顶
createdTsint选填修改创建时间(Unix 秒)

cflow 数据库附件​

创建并挂到笔记 — POST /api/v1/resource/db/create​

参数位置类型必填说明
memoIdbodyint必填笔记 ID(数据库附件会挂到这篇笔记上)
filenamebodystring必填数据库名称,不带 .cfdb 后缀(统一由服务端拼接)

执行 SQL — POST /api/v1/resource/db/exec/{resourceId}​

参数位置类型必填说明
resourceIdpathint必填资源 ID
sqlbodystring必填SQL 文本,可含多条语句(用 ; 分隔),整批在同一事务中执行,任一语句失败整批回滚
baseVersionbodyint选填乐观锁:与当前版本不一致返回 409,防止并发覆盖

返回 {results, version, size, mutated, writeCount}:成功批 results 只含最后一条语句的结果——查询语句带 columns/rows(最多 1000 行,超出标记 hasMore),非查询语句带 affected(影响行数)。mutated 表示本批是否包含变更(纯查询不推进版本);writeCount 为本批写操作语句条数。

任一语句失败时返回 400,Body 含 message(失败语句序号与原因)、statementIndex(从 0 开始)与此前已成功语句的 results,整批已回滚。

支持建表/删表、增删改行列、改字段、索引、视图、触发器、JOIN、CTE、窗口函数等;不支持 PRAGMA、ATTACH、BEGIN/COMMIT(整批已在一个事务内)。

Python 示例​

以下示例使用 requests 库(pip install requests)。

import requests

BASE = "https://cflow.cc"
TOKEN = "你的API Token"
headers = {"Authorization": f"Bearer {TOKEN}"}
json_headers = {**headers, "Content-type": "application/json"}

新增笔记​

resp = requests.post(f"{BASE}/api/v1/memo", headers=json_headers, json={
"content": "通过 API 创建的笔记 #api",
"spaceId": "", # 选填,默认空间
"skipWebhook": "1", # 选填,批量导入时跳过自动化
})
memo_id = resp.json()["MemoId"]

查询笔记​

# 单篇
memo = requests.get(f"{BASE}/api/v1/memo/{memo_id}", headers=headers).json()

# 列表(分页)
memos = requests.get(f"{BASE}/api/v1/memo", headers=headers, params={
"rowStatus": "NORMAL",
"offset": 0,
"limit": 20,
}).json()

修改笔记​

resp = requests.patch(f"{BASE}/api/v1/memo/{memo_id}", headers=json_headers, json={
"content": "修改后的内容",
})

删除笔记​

resp = requests.delete(f"{BASE}/api/v1/memo/{memo_id}", params={"removeFromKanban": "1"}, headers=headers)

上传附件​

multipart/form-data 表单,先上传得到附件 ID,再挂到笔记上:

参数位置类型必填说明
fileform-datafile必填文件本体
content_typeform-datastring选填文件 MIME 类型,写法见下

返回附件对象,附件 ID 在 id 字段(小写,与笔记的 MemoId 不同)。

文件类型怎么写(重要)​

附件的 MIME 类型决定它在 cflow 里能否被正确识别和预览,请按文件的真实格式指定。

常见格式对照:

文件类型写法
.pngimage/png
.jpg / .jpegimage/jpeg
.gifimage/gif
.webpimage/webp
.svgimage/svg+xml
.pdfapplication/pdf
.txt / .mdtext/plain
.htmltext/html
.mp4video/mp4
.mp3audio/mpeg
.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.pptxapplication/vnd.openxmlformats-officedocument.presentationml.presentation
.zipapplication/zip
# 1. 上传文件:三元组第三个参数就是文件类型,按真实格式写
files = {"file": ("照片.png", open("照片.png", "rb"), "image/png")}
resource_id = requests.post(f"{BASE}/api/v1/resource/blob", headers=headers, files=files).json()["id"]

# 2. 挂到笔记(创建时挂:resourceIdList 一样可用)
resp = requests.patch(f"{BASE}/api/v1/memo/{memo_id}", headers=json_headers, json={
"resourceIdList": [resource_id],
})

下载附件​

# 加 download=1 以「保存文件」方式返回(带原始文件名);不加则按预览(inline)返回
resp = requests.get(f"{BASE}/o/r/{resource_id}", params={"download": "1"}, headers=headers)
resp.raise_for_status()
with open("照片.png", "wb") as f:
f.write(resp.content)

操作 cflow 数据库​

# 创建数据库附件并挂到笔记
resp = requests.post(f"{BASE}/api/v1/resource/db/create", headers=json_headers,
json={"memoId": memo_id, "filename": "记账本"})
resp.raise_for_status()
db_id = resp.json()["id"]

# 建表 + 插入 + 查询,一次请求整批执行(一个事务,响应只含最后一条 SELECT 的结果)
# 插入多条数据务必像这样合并成一批(多值 INSERT 或分号分隔的多条语句),不要每条数据请求一次:
# 逐条请求容易被 429 拒绝
sql = """
CREATE TABLE IF NOT EXISTS bills (id INTEGER PRIMARY KEY, item TEXT, amount REAL, day TEXT);
INSERT INTO bills (item, amount, day) VALUES ('买菜', 35.5, '2026-10-28'), ('打车', 18.0, '2026-10-28');
SELECT item, amount FROM bills ORDER BY amount DESC;
"""
resp = requests.post(f"{BASE}/api/v1/resource/db/exec/{db_id}", headers=json_headers, json={"sql": sql})
resp.raise_for_status()
for stmt in resp.json()["results"]: # 成功批只含最后一条语句的结果
if stmt["kind"] == "rows":
print(stmt["columns"], stmt["rows"]) # 查询结果
else:
print("affected:", stmt.get("affected", 0))

注意事项​

  • Token 的读写权限与空间范围会实际生效:只读 Token 无法创建/修改,空间范围外的操作会被拒绝。
  • 批量操作请控制频率,过快的请求会被限流。
  • cflow 数据库的 SQL 为 SQLite 方言;多语句整批在同一事务中执行,任一语句失败整批回滚;成功批只返回最后一条语句的结果。插入多条数据务必合并成一次请求,不要每条数据请求一次。
  • 更完整的 Token 管理与 AI 智能体接入说明见 API 与 Token。