🎉各位开发者好~

集成前请仔细阅读该文档，有任何疑问请邮件690090@qq.com或微信w690090。

更新日志

日期	接口 / 模块	变更说明
2026/06/30	搜索文章	根据关键字搜索文章
2026/06/20	上传文件	新增录音类型 type=record（m4a/mp3/wav/aac/amr/ogg/caf，单文件 ≤ 50MB）；图片仍 ≤ 10MB
2026/06/05	获取订阅信息 / me	新增「获取订阅信息」接口；/v1/me 响应内嵌 subscription 摘要
2026/06/02	获取卡片扩展列表	新增（GET 接口）
2026/06/01	获取用户基本信息	返回字段新增 email、avatar
2026/06/01	更新卡片分享状态	新增（PATCH 接口）
2026/06/01	获取卡片	返回字段新增 shareStatus、sharePassword
2026/05/27	上传文件	支持 webp 格式；返回字段新增 sha256、dedup（相同内容自动去重）
2026/05/27	获取上传结果	返回字段新增 sha256、size、mime、dedup
2026/05/27	错误码	新增 1011（限流）
2026/05/27	限流说明	新增章节
2026/05/27	更新卡片	新增（PATCH 接口）
2026/05/27	卡片列表	新增（GET 接口）
2026/05/27	创建空间	新增
2026/05/27	获取单个空间	新增
2026/05/27	更新空间	新增
2026/05/17	上传文件	新增
2026/05/17	获取上传结果	新增
2026/05/15	创建卡片	支持分享参数
2026/03/25	搜索卡片	根据关键字搜索卡片
2026/01/23	创建卡片	支持空间参数
2026/01/23	创建卡片	支持附件参数
2026/01/23	获取最近更新卡片列表	支持空间参数
2026/01/23	扩展卡片	新增
2026/01/23	获取空间列表	新增

基本信息

• 接口公共地址：https://api.writeathon.cn

• 请求信息格式：JSON

• 响应信息格式：JSON

所有请求必须在请求头（request header）加入x-writeathon-token参数，其值为用户提供的集成Token（由用户自主生成），否则校验失败 接口中的用户id可在设置→集成中获取

响应信息结构

参数	说明
success	请求状态，true/false
data	返回数据（json对象），具体信息见各接口返回参数
action	接口行为，具体信息见各接口信息
errorCode	错误码，请求失败时返回，见错误码说明
message	错误信息，请求失败时返回

错误码

错误码	说明
1000	未分类异常
1001	没有高级版权限
1002	没有提供集成Token
1003	集成Token不存在
1004	没有权限
1005	目标资源不存在（卡片 / 空间 / 上传任务）
1011	触发限流，响应携带 Retry-After 头
7013	没有存储配额
7014	存储配额不足
7016	不支持的文件类型
7017	文件大小超出限制

限流说明

集成 API 对单个用户做 30 请求/秒 的限流（滑动 1 秒窗口）。

超限时服务端返回标准 HTTP 429 Too Many Requests：

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "success": false,
  "message": "QPS limited",
  "errorCode": 1011
}

• 客户端应当遵从 Retry-After 头退避指定秒数后再重试
• 同一用户的多个集成 Token 共用 30 req/s 额度
• 建议主动节流到 ≤ 20 req/s 留出缓冲

接口

1. 获取用户基本信息

1.1 接口信息

• 接口地址：/v1/me

• 请求方式：GET

• 接口行为：me

1.2 请求参数

无

1.3 返回参数

参数	类型	说明
id	字符串	用户id
username	字符串	用户名
email	字符串	邮箱，未设置时为空字符串
avatar	字符串	头像地址，未设置时为空字符串
subscription	对象	订阅状态摘要，结构见 §18 获取订阅信息

2. 创建卡片

2.1 接口信息

• 接口地址：/v1/users/:id/cards，:id为用户id

• 请求方式：POST

• 接口行为：create：添加时返回，append：追加时返回

2.2 请求参数

参数	类型	是否必填	说明
title	字符串	否	卡片标题，若为空则自动创建，若存在则会追加内容到指定卡片，最大长度100个字符（1个中文字算1个字符）
content	字符串	是	卡片内容，最大长度5000个字符（1个中文字算1个字符）
space	字符串	否	空间id，不传为默认空间
attachments	字符串	否	附件，json数组字符串，传参前需要将数组转换为字符串，即将json对象：[{"type":"link"}]，转换为字符串，具体参数见attachments参数
shareStatus	数值	否	0：不分享（默认），1：分享

2.2.1 attachments参数

参数	类型	是否必填	说明
type	字符串	是	可选值，link：链接，image：图片
title	字符串	是	名称/标题
url	字符串	是	链接地址/图片地址
excerpt	字符串	否	摘要
from	字符串	否	来源，type=link时填default
content	字符串	否	链接原文或图片说明

2.3 返回参数

无

3. 获取最近更新的卡片列表

3.1 接口信息

• 接口地址：/v1/users/:id/cards/recent，:id为用户id

• 请求方式：GET

• 接口行为：recent_card_list

• 备注：返回最近修改的10个卡片列表，包括标题和id信息

3.2 请求参数

参数	类型	是否必填	说明
exclude_date_title	布尔	否	是否排除日期类型标题（一般为系统自动生成），默认为false
space	字符串	否	空间id，不传为默认空间

3.3 返回参数

返回对象数组类型，对象属性如下：

参数	类型	说明
_id	字符串	卡片id
title	字符串	卡片标题

4. 获取卡片

4.1 接口信息

• 接口地址：/v1/users/:id/cards/get，:id为用户id

• 请求方式：POST

• 接口行为：get_card

4.2 请求参数

参数	类型	是否必填	说明
title	字符串	title和id必填其一	标题
id	字符串	title和id必填其一	id

4.3 返回参数

返回对象类型，对象属性如下：

参数	类型	说明
_id	字符串	卡片id
title	字符串	卡片标题
content	字符串	卡片内容
created	日期	创建时间
updated	日期	更新时间
shareStatus	数值	分享状态，0：关闭；1：开启
sharePassword	字符串	分享密码，未设置时为空字符串

5. 写作拾贝

5.1 接口信息

• 接口地址：/v1/users/:id/writing-pick，:id为用户id

• 请求方式：POST

• 接口行为：writing_pick

5.2 请求参数

参数	类型	是否必填	说明
type	字符串	否	类型，all/page/card，默认为all
limit	数字	否	返回数量，1-10，默认：10

5.3 返回参数

返回列表对象类型，对象属性如下：

参数	类型	说明
id	字符串	id
title	字符串	标题
content	字符串	内容
created	日期	创建时间
updated	日期	更新时间
type	字符串	类型

6. 扩展卡片

6.1 接口信息

• 接口地址：/v1/users/:id/cards/extend，:id为用户id

• 请求方式：POST

• 接口行为：extend

6.2 请求参数

参数	类型	是否必填	说明
title	字符串	否	卡片标题，若为空则自动创建，若存在则会追加内容到指定卡片，最大长度100个字符（1个中文字算1个字符）
content	字符串	是	卡片内容，最大长度5000个字符（1个中文字算1个字符）
parent	字符串	是	扩展卡片id
attachments	字符串	否	附件，json数组字符串，传参前需要将数组转换为字符串，即将json对象：[{"type":"link"}]，转换为字符串，具体参数见attachments参数

6.3 返回参数

无

7. 获取空间列表

7.1 接口信息

• 接口地址：/v1/users/:id/spaces，:id为用户id

• 请求方式：GET

• 接口行为：space_list

• 备注：返回最近修改的50个空间，默认空间始终位列第一

7.2 请求参数

无

7.3 返回参数

返回对象数组类型，对象属性如下：

参数	类型	说明
id / _id	字符串	空间 id；默认空间用 id（字面值 "default"），非默认空间用 _id（ObjectId），客户端兜底兼容两者
title	字符串	标题
description	字符串	说明
emojiIcon	字符串	emoji 图标
style	字符串	样式名（mint/grapefruit/bittersweet/sunflower/grass/aqua/blue/lavander/pink/dark）
cover	字符串	封面编号（"0"-"N" 字符串），不是 URL
order	数字	排序
created	日期	创建时间
updated	日期	更新时间

注：默认空间的 author 字段是空字符串占位，不要拿它做权限判断。

8. 搜索卡片

8.1 接口信息

• 接口地址：/v1/users/:id/cards/search，:id为用户id

• 请求方式：POST

• 接口行为：search_card

• 备注：根据关键字搜索卡片，返回最多50个卡片

8.2 请求参数

参数	类型	是否必填	说明
keyword	字符串	是	关键字
sortString	字符串	否	排序，如：-updated,
space	字符串	否	空间id，不传为默认空间
limit	数字	否	返回数量，最大50

8.3 返回参数

返回对象数组类型，对象属性如下：

参数	类型	说明
title	字符串	卡片标题
content	字符串	卡片内容
parent	字符串	扩展卡片id
attachments	字符串	附件，json数组字符串，具体参数见attachments参数

9. 上传文件

9.1 接口信息

• 接口地址：/v1/users/:id/upload，:id为用户id

• 请求方式：POST

• Content-Type：multipart/form-data

• 接口行为：upload

• 备注：异步上传，调用后返回任务id，通过「获取上传结果」接口轮询上传状态。支持图片（image）与录音（record）两类。相同内容文件自动去重：服务端按 sha256 索引，命中已上传过的相同内容文件时不会重复占用存储配额，taskId 立即标记为 completed。

9.2 请求参数

Query参数：

参数	类型	是否必填	说明
type	字符串	否	文件类型，可选值：image（图片，默认值）、record（录音）

Form-data参数：

参数	类型	是否必填	说明
file	文件	是	上传的文件。type=image 时支持 png、jpg、jpeg、gif、webp，单文件 ≤ 10MB；type=record 时支持 m4a、mp3、wav、aac、amr、ogg、caf，单文件 ≤ 50MB

9.3 返回参数

参数	类型	说明
taskId	字符串	上传任务id，用于查询上传结果
sha256	字符串	文件内容的 SHA-256 哈希（64位 hex），客户端可用于本地内容校验或重传判定
dedup	布尔	是否命中去重快通道；true 表示服务端已有相同 sha256 的历史上传，未重复上传到对象存储

9.4 错误说明

错误码	说明
7013	没有存储配额
7014	存储配额不足（命中 dedup 时不消耗配额）
7016	不支持的文件类型
7017	文件大小超出限制

10. 获取上传结果

10.1 接口信息

• 接口地址：/v1/users/:id/upload/:taskId，:id为用户id，:taskId为上传任务id

• 请求方式：GET

• 接口行为：upload_result

• 备注：上传为异步操作，调用上传接口后需轮询此接口获取结果，建议间隔1-2秒。任务结果缓存1小时后过期；过期后查询返回 errorCode: 1005。命中去重（dedup）时第一次轮询就能拿到 completed 状态。

10.2 请求参数

无

10.3 返回参数

参数	类型	说明
status	字符串	上传状态：uploading（上传中）、completed（完成）、failed（失败）
url	字符串	文件访问链接，status=completed 时返回
hash	字符串	文件七牛 etag，status=completed 时返回
key	字符串	文件存储 key，status=completed 时返回
sha256	字符串	文件内容 SHA-256，status=completed 时返回
size	数字	文件字节数，status=completed 时返回
mime	字符串	文件 MIME 类型（图片如 image/png，录音如 audio/mp4），status=completed 时返回
dedup	布尔	是否命中去重快通道（与上传接口返回的 dedup 字段一致）

11. 更新卡片

11.1 接口信息

• 接口地址：/v1/users/:id/cards/:cardId，:id为用户id，:cardId为卡片id

• 请求方式：PATCH

• 接口行为：update_card

• 备注：部分更新，未提供的字段保持原值。

11.2 请求参数

参数	类型	是否必填	说明
title	字符串	否	卡片标题
content	字符串	否	卡片内容
space	字符串	否	空间 id；传 null 或省略字段表示移到默认空间；避免传 "default" 字面值
attachments	数组/字符串	否	附件，支持 JSON 数组或 JSON 数组字符串；结构同attachments参数

11.3 返回参数

返回更新后的卡片对象，字段与「获取卡片」一致。

11.4 错误说明

错误码	说明
1004	没有权限（非作者）
1005	卡片不存在
1000	更新失败

12. 卡片列表

12.1 接口信息

• 接口地址：/v1/users/:id/cards，:id为用户id

• 请求方式：GET

• 接口行为：list_cards

• 备注：分页返回指定空间下的卡片。

12.2 请求参数

Query参数：

参数	类型	是否必填	说明
space	字符串	否	空间 id；不传或传 "default" 表示默认空间
page	数字	否	页码，从 1 开始，默认 1
limit	数字	否	每页数量，默认 20，上限 100
sort	字符串	否	mongoose 排序字符串，如 -updated / -created / created，默认 -updated

12.3 返回参数

参数	类型	说明
list	对象数组	卡片列表，对象字段同「获取卡片」并含其他扩展字段
total	数字	该空间下卡片总数
page	数字	当前页码
limit	数字	当前每页数量
hasMore	布尔	是否还有下一页

13. 创建空间

13.1 接口信息

• 接口地址：/v1/users/:id/spaces，:id为用户id

• 请求方式：POST

• 接口行为：create_space

13.2 请求参数

参数	类型	是否必填	说明
title	字符串	是	空间标题
description	字符串	否	说明
emojiIcon	字符串	否	emoji 图标
style	字符串	否	样式名，见「获取空间列表」7.3 style 枚举，默认 dark
cover	字符串	否	封面编号，默认 "0"

13.3 返回参数

返回创建的空间对象，字段同「获取空间列表」7.3。

14. 获取单个空间

14.1 接口信息

• 接口地址：/v1/users/:id/spaces/:spaceId，:id为用户id，:spaceId为空间id

• 请求方式：GET

• 接口行为：get_space

• 备注：spaceId = default 返回常量默认空间（与空间列表中第一个一致）。

14.2 请求参数

无

14.3 返回参数

返回空间对象，字段同「获取空间列表」7.3。

14.4 错误说明

错误码	说明
1004	没有权限（非作者）
1005	空间不存在

15. 更新空间

15.1 接口信息

• 接口地址：/v1/users/:id/spaces/:spaceId，:id为用户id，:spaceId为空间id

• 请求方式：PATCH

• 接口行为：update_space

• 备注：部分更新，未提供的字段保持原值。默认空间（spaceId=default）禁止修改，返回 1004 NO_PERMISSION。

15.2 请求参数

参数	类型	是否必填	说明
title	字符串	否	空间标题
description	字符串	否	说明
emojiIcon	字符串	否	emoji 图标
style	字符串	否	样式名
cover	字符串	否	封面编号

15.3 返回参数

返回更新后的空间对象。

15.4 错误说明

错误码	说明
1004	没有权限（非作者 / 默认空间禁改）
1005	空间不存在
1000	更新失败

16. 更新卡片分享状态

16.1 接口信息

• 接口地址：/v1/users/:id/cards/:cardId/share，:id为用户id，:cardId为卡片id

• 请求方式：PATCH

• 接口行为：update_card_share

• 备注：开启分享（shareStatus=1）时会对卡片内容、分享标题、分享内容做敏感词审核，未通过则自动关闭分享并返回 7001。

16.2 请求参数

参数	类型	是否必填	说明
shareStatus	数值	是	分享状态，0：关闭；1：开启
sharePassword	字符串	否	分享密码，不传则清空
shareTitle	字符串	否	分享标题（用于发布页展示）
shareContent	字符串	否	分享内容（用于发布页展示）

16.3 返回参数

返回对象类型，对象属性如下：

参数	类型	说明
_id	字符串	卡片id
shareStatus	数值	分享状态
sharePassword	字符串	分享密码

16.4 错误说明

错误码	说明
1004	没有权限（非作者）
1005	卡片不存在
7001	内容审核未通过
1000	更新失败

17. 获取卡片扩展列表

17.1 接口信息

• 接口地址：/v1/users/:id/cards/:cardId/extends，:id为用户id，:cardId为卡片id

• 请求方式：GET

• 接口行为：card_extends

• 接口说明：获取指定卡片的直接扩展卡片（子卡片）列表，默认按扩展顺序 extendOrder 排序。

17.2 请求参数

参数	类型	是否必填	说明
sort	字符串	否	排序串，默认 extendOrder；可传 -created / -updated 等

17.3 返回参数

返回对象类型，list 为扩展卡片数组，每个对象字段如下：

参数	类型	说明
_id	字符串	卡片id
title	字符串	卡片标题
content	字符串	卡片内容
created	日期	创建时间
updated	日期	更新时间
parent	字符串	父卡片id（即 :cardId）
root	字符串	根卡片id
extendOrder	数值	扩展排序值，越小越靠前

17.4 错误说明

错误码	说明
1004	没有权限（非作者）
1005	卡片不存在
1000	获取失败

18. 获取订阅信息

18.1 接口信息

• 接口地址：/v1/users/:id/subscription，:id为用户id

• 请求方式：GET

• 接口行为：subscription

• 接口说明：获取用户当前订阅状态摘要。非会员同样可调用（返回 isValid: false）。该摘要同时内嵌于 /v1/me 响应，客户端按场景取用、无需额外轮询。

18.2 请求参数

无

18.3 返回参数

参数	类型	说明
isValid	布尔	是否有未过期的有效订阅
isForever	布尔	是否终身会员
startAt	日期 / null	当前有效订阅开始时间；非会员为 null
endAt	日期 / null	当前有效订阅结束时间；非会员为 null
plan	对象 / null	方案信息 { id, title, interval }；title 为多语言对象 {zhCN, enUS}；非会员为 null

无有效订阅时 isValid/isForever=false、startAt/endAt/plan=null。

19. 搜索文章

19.1 接口信息

• 接口地址：/v1/users/:id/pages/search，:id为用户id

• 请求方式：POST

• 接口行为：search_page

• 备注：根据关键字搜索文章（仅搜索 type=0 的普通文章），返回最多 50 篇文章。关键字为空时返回最近更新的前 10 篇。

19.2 请求参数

参数	类型	是否必填	说明
keyword	字符串	否	关键字；为空时返回最近更新的前 10 篇
isIncludeContent	布尔	否	是否搜索正文，默认 true；为 false 时仅匹配标题
space	字符串	否	空间id，不传为默认空间
limit	数字	否	返回数量，最大 50

19.3 返回参数

返回对象类型，对象属性如下：

参数	类型	说明
list	对象数组	文章列表（不含正文 content），对象字段见下
total	数字	匹配到的文章总数

list 中每个文章对象字段：

参数	类型	说明
_id	字符串	文章id
title	字符串	文章标题
story	对象	所属故事（含 notebook 信息）
created	日期	创建时间
updated	日期	更新时间