外观
API
2012字约7分钟
2024-12-20
🎉各位开发者好~
集成前请仔细阅读该文档，有任何疑问请邮件690090@qq.com或微信w690090。
更新日志
2026/05/17
上传文件：新增
获取上传结果：新增
2026/05/15
- 创建卡片：支持分享参数
2026/03/25
- 搜索卡片：根据关键字搜索卡片
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 | 项目不存在 |
| 7013 | 没有存储配额 |
| 7014 | 存储配额不足 |
| 7016 | 不支持的文件类型 |
| 7017 | 文件大小超出限制 |
接口
1. 获取用户基本信息
1.1 接口信息
接口地址：
/v1/me请求方式：
GET接口行为：
me
1.2 请求参数
无
1.3 返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| id | 字符串 | 用户id |
| username | 字符串 | 用户名 |
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 | 日期 | 更新时间 |
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 |
| title | 字符串 | 标题 |
| description | 字符串 | 说明 |
| created | 日期 | 创建时间 |
| updated | 日期 | 更新时间 |
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请求方式：
POSTContent-Type：
multipart/form-data接口行为：
upload备注：异步上传，调用后返回任务id，通过「获取上传结果」接口轮询上传状态。目前仅支持图片类型。
9.2 请求参数
Query参数：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| type | 字符串 | 否 | 文件类型，目前仅支持：image（默认值） |
Form-data参数：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| file | 文件 | 是 | 上传的文件，支持格式：png、jpg、jpeg、gif，单文件大小限制：10MB |
9.3 返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| taskId | 字符串 | 上传任务id，用于查询上传结果 |
9.4 错误说明
| 错误码 | 说明 |
|---|---|
| 7013 | 没有存储配额 |
| 7014 | 存储配额不足 |
| 7016 | 不支持的文件类型 |
| 7017 | 文件大小超出限制 |
10. 获取上传结果
10.1 接口信息
接口地址：
/v1/users/:id/upload/:taskId，:id为用户id，:taskId为上传任务id请求方式：
GET接口行为：
upload_result备注：上传为异步操作，调用上传接口后需轮询此接口获取结果，建议间隔1-2秒。任务结果缓存1小时后过期。
10.2 请求参数
无
10.3 返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| status | 字符串 | 上传状态：uploading（上传中）、completed（完成）、failed（失败） |
| url | 字符串 | 文件访问链接，status=completed时返回 |
| hash | 字符串 | 文件hash值，status=completed时返回 |
| key | 字符串 | 文件存储key，status=completed时返回 |