思源笔记用户指南

思源笔记最新消息

🍼新手引导

快速上手思源笔记

基本编辑能力

✏️基础操作

⛓️基础块

🧬高级块

📊数据库

🛹特色功能

🚀高级操作

💎会员特权

🖼️主题推荐

🔌常用插件

🔡代码片段

💬交流区

❇️思源进阶

思源笔记公开 API

type

status

date

slug

summary

规范

参数和返回值

端点：http://127.0.0.1:6806

均是 POST 方法

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

返回值

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

鉴权

在设置 - 关于里查看 API token，请求标头：Authorization: Token xxx

笔记本

列出笔记本

/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：新标题

返回值

通过 id 重命名文档：

/api/filetree/renameDocByID

参数

id：文档 ID
title：新标题

返回值

删除文档

/api/filetree/removeDoc

参数

notebook：笔记本 ID
path：文档路径

返回值

通过 id 删除文档：

/api/filetree/removeDocByID

参数

id：文档 ID

返回值

移动文档

/api/filetree/moveDocs

参数

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

返回值

通过 id 移动文档：

/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: 精度为毫秒

类型过滤

性能优化

Last update: 2025-06-07

🤖 AI 问答

通过【ima知识库】思源笔记，AI 会帮你解决思源笔记的常见问题。

🔮 QQ交流群

🗣️ 声明&反馈

本站点非官方站点，仅供参考。可能存在错误或疏漏。

欢迎在下方列表反馈，共建指南。

思源本身的问题请提交 github issues ➡️