思源笔记公开 API

规范

参数和返回值

• 端点：http://127.0.0.1:6806

• 均是 POST 方法

• 需要带参的接口，参数为 JSON 字符串，放置到 body 里，标头 Content-Type 为 application/json

• 返回值
• code：非 0 为异常情况
• msg：正常情况下是空字符串，异常情况下会返回错误文案
• data：可能为 {}、[] 或者 NULL，根据不同接口而不同

鉴权

笔记本

列出笔记本

• /api/notebook/lsNotebooks

• 不带参

• 返回值

打开笔记本

• /api/notebook/openNotebook

• 参数
• notebook：笔记本 ID

• 返回值

关闭笔记本

• /api/notebook/closeNotebook

• 参数
• notebook：笔记本 ID

• 返回值

重命名笔记本

• /api/notebook/renameNotebook

• 参数
• notebook：笔记本 ID

• 返回值

创建笔记本

• /api/notebook/createNotebook

• 参数

• 返回值

删除笔记本

• /api/notebook/removeNotebook

• 参数
• notebook：笔记本 ID

• 返回值

获取笔记本配置

• /api/notebook/getNotebookConf

• 参数
• notebook：笔记本 ID

• 返回值

保存笔记本配置

• /api/notebook/setNotebookConf

• 参数
• notebook：笔记本 ID

• 返回值

文档

通过 Markdown 创建文档

• /api/filetree/createDocWithMd

• 参数
• notebook：笔记本 ID
• path：文档路径，需要以 / 开头，中间使用 / 分隔层级（这里的 path 对应数据库 hpath 字段）
• markdown：GFM Markdown 内容

• 返回值
• data：创建好的文档 ID
• 如果使用同一个 path 重复调用该接口，不会覆盖已有文档

重命名文档

• /api/filetree/renameDoc

• 参数
• notebook：笔记本 ID
• path：文档路径
• title：新标题

• 返回值

• /api/filetree/renameDocByID

• 参数
• id：文档 ID
• title：新标题

• 返回值

删除文档

• /api/filetree/removeDoc

• 参数
• notebook：笔记本 ID
• path：文档路径

• 返回值

• /api/filetree/removeDocByID

• 参数
• id：文档 ID

• 返回值

移动文档

• /api/filetree/moveDocs

• 参数
• fromPaths：源路径
• toNotebook：目标笔记本 ID
• toPath：目标路径

• 返回值

• /api/filetree/moveDocsByID

• 参数
• fromIDs：源文档 ID
• toID：目标父文档 ID

• 返回值

根据路径获取人类可读路径

• /api/filetree/getHPathByPath

• 参数
• notebook：笔记本 ID
• path：路径

• 返回值

根据 ID 获取人类可读路径

• /api/filetree/getHPathByID

• 参数
• id：块 ID

• 返回值

根据 ID 获取存储路径

• /api/filetree/getPathByID

• 参数
• id：块 ID

• 返回值

根据人类可读路径获取 IDs

• /api/filetree/getIDsByHPath

• 参数
• path：人类可读路径
• notebook：笔记本 ID

• 返回值

资源文件

上传资源文件

• /api/asset/upload

• 参数为 HTTP Multipart 表单
• assetsDirPath：资源文件存放的文件夹路径，以 data 文件夹作为根路径，比如： 常规情况下建议用第一种，统一存放到工作空间资源文件夹下，放在子目录有一些副作用，请参考用户指南资源文件章节。
• "/assets/"：工作空间/data/assets/ 文件夹
• "/assets/sub/"：工作空间/data/assets/sub/ 文件夹
• file[]：上传的文件列表

• 返回值
• errFiles：处理时遇到错误的文件名
• succMap：处理成功的文件，key 为上传时的文件名，value 为 assets/foo-id.png，用于将已有 Markdown 内容中的资源文件链接地址替换为上传后的地址

块

插入块

• /api/block/insertBlock

• 参数
• dataType：待插入数据类型，值可选择 markdown 或者 dom
• data：待插入的数据
• nextID：后一个块的 ID，用于锚定插入位置
• previousID：前一个块的 ID，用于锚定插入位置
• parentID：父块 ID，用于锚定插入位置
nextID、previousID、parentID 三个参数必须至少存在一个有值，优先级为 nextID > previousID > parentID

• 返回值
• action.data：新插入块生成的 DOM
• action.id：新插入块的 ID

插入前置子块

• /api/block/prependBlock

• 参数
• dataType：待插入数据类型，值可选择 markdown 或者 dom
• data：待插入的数据
• parentID：父块的 ID，用于锚定插入位置

• 返回值
• action.data：新插入块生成的 DOM
• action.id：新插入块的 ID

插入后置子块

• /api/block/appendBlock

• 参数
• dataType：待插入数据类型，值可选择 markdown 或者 dom
• data：待插入的数据
• parentID：父块的 ID，用于锚定插入位置

• 返回值
• action.data：新插入块生成的 DOM
• action.id：新插入块的 ID

更新块

• /api/block/updateBlock

• 参数
• dataType：待更新数据类型，值可选择 markdown 或者 dom
• data：待更新的数据
• id：待更新块的 ID

• 返回值
• action.data：更新块生成的 DOM

删除块

• /api/block/deleteBlock

• 参数
• id：待删除块的 ID

• 返回值

移动块

• /api/block/moveBlock

• 参数
• id：待移动块 ID
• previousID：前一个块的 ID，用于锚定插入位置
• parentID：父块的 ID，用于锚定插入位置，previousID 和 parentID 不能同时为空，同时存在的话优先使用 previousID

• 返回值

折叠块

• /api/block/foldBlock

• 参数
• id：待折叠块的 ID

• 返回值

展开块

• /api/block/unfoldBlock

• 参数
• id：待展开块的 ID

• 返回值

获取块 kramdown 源码

• /api/block/getBlockKramdown

• 参数
• id：待获取块的 ID

• 返回值

获取子块

• /api/block/getChildBlocks

• 参数
• id：父块 ID
• 标题下方块也算作子块

• 返回值

转移块引用

• /api/block/transferBlockRef

• 参数
• fromID：定义块 ID
• toID：目标块 ID
• refIDs：指向定义块 ID 的引用所在块 ID，可选，如果不指定，所有指向定义块 ID 的块引用 ID 都会被转移

• 返回值

属性

设置块属性

• /api/attr/setBlockAttrs

• 参数
• id：块 ID
• attrs：块属性，自定义属性必须以 custom- 作为前缀

• 返回值

获取块属性

• /api/attr/getBlockAttrs

• 参数
• id：块 ID

• 返回值

SQL

执行 SQL 查询

• /api/query/sql

• 参数
• stmt：SQL 脚本

• 返回值

提交事务

• /api/sqlite/flushTransaction

• 不带参

• 返回值

模板

渲染模板

• /api/template/render

• 参数
• id：调用渲染所在的文档 ID
• path：模板文件绝对路径

• 返回值

渲染 Sprig

• /api/template/renderSprig

• 参数
• template：模板内容

• 返回值

文件

获取文件

• /api/file/getFile

• 参数
• path：工作空间路径下的文件路径

• 返回值
• 响应状态码 200: 文件内容
• 响应状态码 202: 异常信息
• code: 非零的异常值
• 1: 参数解析错误
• 403: 无访问权限 (文件不在工作空间下)
• 404: 未找到 (文件不存在)
• 405: 方法不被允许 (这是一个目录)
• 500: 服务器错误 (文件查询失败 / 文件读取失败)
• msg: 一段描述错误的文本

写入文件

• /api/file/putFile

• 参数为 HTTP Multipart 表单
• path：工作空间路径下的文件路径
• isDir：是否为创建文件夹，为 true 时仅创建文件夹，忽略 file
• modTime：最近访问和修改时间，Unix time
• file：上传的文件

• 返回值

删除文件

• /api/file/removeFile

• 参数
• path：工作空间路径下的文件路径

• 返回值

重命名文件

• /api/file/renameFile

• 参数
• path：工作空间路径下的文件路径
• newPath：新的文件路径

• 返回值

列出文件

• /api/file/readDir

• 参数
• path：工作空间路径下的文件夹路径

• 返回值

导出

导出 Markdown 文本

• /api/export/exportMdContent

• 参数
• id：要导出的文档块 ID

• 返回值
• hPath：人类可读的路径
• content：Markdown 内容

导出文件与目录

• /api/export/exportResources

• 参数
• paths：要导出的文件或文件夹路径列表，相同名称的文件/文件夹会被覆盖
• name：（可选）导出的文件名，未设置时默认为 export-YYYY-MM-DD_hh-mm-ss.zip

• 返回值
• path：创建的 .zip 文件路径
• zip-file-name.zip 中的目录结构如下所示：
• zip-file-name
• boot
• langs
• conf.json
• index.html

转换

Pandoc

• /api/convert/pandoc

• 工作目录
• 执行调用 pandoc 命令时工作目录会被设置在 工作空间/temp/convert/pandoc/${test} 下
• 可先通过 API 写入文件 将待转换文件写入该目录
• 然后再调用该 API 进行转换，转换后的文件也会被写入该目录
• 最后调用 API 获取文件 获取转换后的文件内容
• 或者调用 API 通过 Markdown 创建文档
• 或者调用内部 API importStdMd 将转换后的文件夹直接导入

• 参数
• args：Pandoc 命令行参数

• 返回值
• path：工作空间下的路径

通知

推送消息

• /api/notification/pushMsg

• 参数
• timeout：消息持续显示时间，单位为毫秒。可以不传入该字段，默认为 7000 毫秒

• 返回值
• id：消息 ID

推送报错消息

• /api/notification/pushErrMsg

• 参数
• timeout：消息持续显示时间，单位为毫秒。可以不传入该字段，默认为 7000 毫秒

• 返回值
• id：消息 ID

网络

正向代理

• /api/network/forwardProxy

• 参数
• url：转发的 URL
• method：HTTP 方法，默认为 GET
• timeout：超时时间，单位为毫秒，默认为 7000 毫秒
• contentType：HTTP Content-Type，默认为 application/json
• headers：HTTP 请求标头
• payload：HTTP 请求体，对象或者是字符串
• payloadEncoding：pyaload 所使用的编码方案，默认为 text，可选值如下所示
• text
• base64 | base64-std
• base64-url
• base32 | base32-std
• base32-hex
• hex
• responseEncoding：响应数据中 body 字段所使用的编码方案，默认为 text，可选值如下所示
• text
• base64 | base64-std
• base64-url
• base32 | base32-std
• base32-hex
• hex

• 返回值
• bodyEncoding：body 所使用的编码方案，与请求中 responseEncoding 字段一致，默认为 text，可能的值如下所示
• text
• base64 | base64-std
• base64-url
• base32 | base32-std
• base32-hex
• hex

系统

获取启动进度

• /api/system/bootProgress

• 不带参

• 返回值

获取系统版本

• /api/system/version

• 不带参

• 返回值

获取系统当前时间

• /api/system/currentTime

• 不带参

• 返回值
• data: 精度为毫秒