内核 API

内容延续自：https://docs.siyuan-note.club/zh-Hans/reference/api/kernel/

说明

思源笔记是一款前后端分离架构的软件，GoLang 语言作为后端在运行时提供了大量 API 供前端调用。

API 调用格式

在插件系统中调用后端 API, 可以使用插件 API 提供的 fetchPost 和 fetchSyncPost 两个方法, 这两个 API 都会在内部完成自动鉴权已经发送请求。在使用中，注意点如下:

使用 POST 方法

第一个参数为 API route

第二个参数为 post data, 是一个 js object

如果是 fetchPost 方法, 还会有第三个回调函数参数

返回值格式为

{
    "code": 0,
    "msg": "",
    "data": {}
}

code：非 0 为异常情况

msg：正常情况下是空字符串，异常情况下会返回错误文案

data：可能为 {}、[] 或者 NULL，根据不同接口而不同

样例代码

API 大纲

笔记本

列出笔记本

/api/notebook/lsNotebooks

不带参

返回值

{
    "code": 0,
    "msg": "",
    "data": {
        "notebooks": [
            {
                "id": "20210817205410-2kvfpfn",
                "name": "测试笔记本",
                "icon": "1f41b",
                "sort": 0,
                "closed": false
            },
            {
                "id": "20210808180117-czj9bvb",
                "name": "思源笔记用户指南",
                "icon": "1f4d4",
                "sort": 1,
                "closed": false
            }
        ]
    }
}

打开笔记本

/api/notebook/openNotebook

参数

{
    "notebook": "20210831090520-7dvbdv0"
}

notebook：笔记本 ID

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

关闭笔记本

/api/notebook/closeNotebook

参数

{
    "notebook": "20210831090520-7dvbdv0"
}

notebook：笔记本 ID

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

重命名笔记本

/api/notebook/renameNotebook

参数

{
    "notebook": "20210831090520-7dvbdv0",
    "name": "笔记本的新名称"
}

notebook：笔记本 ID

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

创建笔记本

/api/notebook/createNotebook

参数

{
    "name": "笔记本的名称"
}

返回值

{
    "code": 0,
    "msg": "",
    "data": {
        "notebook": {
            "id": "20220126215949-r1wvoch",
            "name": "笔记本的名称",
            "icon": "",
            "sort": 0,
            "closed": false
        }
    }
}

删除笔记本

/api/notebook/removeNotebook

参数

{
    "notebook": "20210831090520-7dvbdv0"
}

notebook：笔记本 ID

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

获取笔记本配置

/api/notebook/getNotebookConf

参数

{
    "notebook": "20210817205410-2kvfpfn"
}

notebook：笔记本 ID

返回值

{
    "code": 0,
    "msg": "",
    "data": {
        "box": "20210817205410-2kvfpfn",
        "conf": {
            "name": "测试笔记本",
            "closed": false,
            "refCreateSavePath": "",
            "createDocNameTemplate": "",
            "dailyNoteSavePath": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}",
            "dailyNoteTemplatePath": ""
        },
        "name": "测试笔记本"
    }
}

保存笔记本配置

/api/notebook/setNotebookConf

参数

{
    "notebook": "20210817205410-2kvfpfn",
    "conf": {
        "name": "测试笔记本",
        "closed": false,
        "refCreateSavePath": "",
        "createDocNameTemplate": "",
        "dailyNoteSavePath": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}",
        "dailyNoteTemplatePath": ""
    }
}

notebook：笔记本 ID

返回值

{
    "code": 0,
    "msg": "",
    "data": {
        "name": "测试笔记本",
        "closed": false,
        "refCreateSavePath": "",
        "createDocNameTemplate": "",
        "dailyNoteSavePath": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}",
        "dailyNoteTemplatePath": ""
    }
}

文档

通过 Markdown 创建文档

/api/filetree/createDocWithMd

参数

{
    "notebook": "20210817205410-2kvfpfn",
    "path": "/foo/bar",
    "markdown": ""
}

notebook：笔记本 ID

path：文档路径，需要以 / 开头，中间使用 / 分隔层级（这里的 path 对应数据库 hpath 字段）

markdown：GFM Markdown 内容

返回值

{
    "code": 0,
    "msg": "",
    "data": "20210914223645-oj2vnx2"
}

data：创建好的文档 ID

如果使用同一个 path 重复调用该接口，不会覆盖已有文档

重命名文档

/api/filetree/renameDoc

参数

{
    "notebook": "20210831090520-7dvbdv0",
    "path": "/20210902210113-0avi12f.sy",
    "title": "文档新标题"
}

notebook：笔记本 ID

path：文档路径

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

删除文档

/api/filetree/removeDoc

参数

{
    "notebook": "20210831090520-7dvbdv0",
    "path": "/20210902210113-0avi12f.sy"
}

notebook：笔记本 ID

path：文档路径

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

移动文档

/api/filetree/moveDocs

参数

{
    "fromPaths": ["/20210917220056-yxtyl7i.sy"],
    "toNotebook": "20210817205410-2kvfpfn",
    "toPath": "/"
}

fromPaths：源路径

toNotebook：目标笔记本 ID

toPath：目标路径

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

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

/api/filetree/getHPathByPath

参数

{
    "notebook": "20210831090520-7dvbdv0",
    "path": "/20210917220500-sz588nq/20210917220056-yxtyl7i.sy"
}

notebook：笔记本 ID

path：路径

返回值

{
    "code": 0,
    "msg": "",
    "data": "/foo/bar"
}

根据 ID 获取人类可读路径

/api/filetree/getHPathByID

参数

{
    "id": "20210917220056-yxtyl7i"
}

id：块 ID

返回值

{
    "code": 0,
    "msg": "",
    "data": "/foo/bar"
}

资源文件

上传资源文件

/api/asset/upload

参数为 HTTP Multipart 表单

assetsDirPath：资源文件存放的文件夹路径，以 data 文件夹作为根路径，比如：

"/assets/"：工作空间/data/assets/ 文件夹

"/assets/sub/"：工作空间/data/assets/sub/ 文件夹

常规情况下建议用第一种，统一存放到工作空间资源文件夹下，放在子目录有一些副作用，请参考用户指南资源文件章节。

file[]：上传的文件列表

返回值

{
    "code": 0,
    "msg": "",
    "data": {
        "errFiles": [""],
        "succMap": {
            "foo.png": "assets/foo-20210719092549-9j5y79r.png"
        }
    }
}

errFiles：处理时遇到错误的文件名

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

块

插入块

/api/block/insertBlock

参数

{
    "dataType": "markdown",
    "data": "foo**bar**{: style=\"color: var(--b3-font-color8);\"}baz",
    "nextID": "",
    "previousID": "20211229114650-vrek5x6",
    "parentID": ""
}

dataType：待插入数据类型，值可选择 markdown 或者 dom

data：待插入的数据

nextID：后一个块的 ID，用于锚定插入位置

previousID：前一个块的 ID，用于锚定插入位置

parentID：父块 ID，用于锚定插入位置

nextID、previousID、parentID 三个参数必须至少存在一个有值，优先级为 nextID > previousID > parentID

返回值

{
    "code": 0,
    "msg": "",
    "data": [
        {
            "doOperations": [
                {
                    "action": "insert",
                    "data": "<div data-node-id=\"20211230115020-g02dfx0\" data-node-index=\"1\" data-type=\"NodeParagraph\" class=\"p\"><div contenteditable=\"true\" spellcheck=\"false\">foo<strong style=\"color: var(--b3-font-color8);\">bar</strong>baz</div><div class=\"protyle-attr\" contenteditable=\"false\"></div></div>",
                    "id": "20211230115020-g02dfx0",
                    "parentID": "",
                    "previousID": "20211229114650-vrek5x6",
                    "retData": null
                }
            ],
            "undoOperations": null
        }
    ]
}

action.data：新插入块生成的 DOM

action.id：新插入块的 ID

插入前置子块

/api/block/prependBlock

参数

{
    "data": "foo**bar**{: style=\"color: var(--b3-font-color8);\"}baz",
    "dataType": "markdown",
    "parentID": "20220107173950-7f9m1nb"
}

dataType：待插入数据类型，值可选择 markdown 或者 dom

data：待插入的数据

parentID：父块的 ID，用于锚定插入位置

返回值

{
    "code": 0,
    "msg": "",
    "data": [
        {
            "doOperations": [
                {
                    "action": "insert",
                    "data": "<div data-node-id=\"20220108003710-hm0x9sc\" data-node-index=\"1\" data-type=\"NodeParagraph\" class=\"p\"><div contenteditable=\"true\" spellcheck=\"false\">foo<strong style=\"color: var(--b3-font-color8);\">bar</strong>baz</div><div class=\"protyle-attr\" contenteditable=\"false\"></div></div>",
                    "id": "20220108003710-hm0x9sc",
                    "parentID": "20220107173950-7f9m1nb",
                    "previousID": "",
                    "retData": null
                }
            ],
            "undoOperations": null
        }
    ]
}

action.data：新插入块生成的 DOM

action.id：新插入块的 ID

插入后置子块

/api/block/appendBlock

参数

{
    "data": "foo**bar**{: style=\"color: var(--b3-font-color8);\"}baz",
    "dataType": "markdown",
    "parentID": "20220107173950-7f9m1nb"
}

dataType：待插入数据类型，值可选择 markdown 或者 dom

data：待插入的数据

parentID：父块的 ID，用于锚定插入位置

返回值

{
    "code": 0,
    "msg": "",
    "data": [
        {
            "doOperations": [
                {
                    "action": "insert",
                    "data": "<div data-node-id=\"20220108003642-y2wmpcv\" data-node-index=\"1\" data-type=\"NodeParagraph\" class=\"p\"><div contenteditable=\"true\" spellcheck=\"false\">foo<strong style=\"color: var(--b3-font-color8);\">bar</strong>baz</div><div class=\"protyle-attr\" contenteditable=\"false\"></div></div>",
                    "id": "20220108003642-y2wmpcv",
                    "parentID": "20220107173950-7f9m1nb",
                    "previousID": "20220108003615-7rk41t1",
                    "retData": null
                }
            ],
            "undoOperations": null
        }
    ]
}

action.data：新插入块生成的 DOM

action.id：新插入块的 ID

更新块

/api/block/updateBlock

参数

{
    "dataType": "markdown",
    "data": "foo bar baz",
    "id": "20211230161520-querkps"
}

dataType：待更新数据类型，值可选择 markdown 或者 dom

data：待更新的数据

id：待更新块的 ID

返回值

{
    "code": 0,
    "msg": "",
    "data": [
        {
            "doOperations": [
                {
                    "action": "update",
                    "data": "<div data-node-id=\"20211230161520-querkps\" data-node-index=\"1\" data-type=\"NodeParagraph\" class=\"p\"><div contenteditable=\"true\" spellcheck=\"false\">foo<strong>bar</strong>baz</div><div class=\"protyle-attr\" contenteditable=\"false\"></div></div>",
                    "id": "20211230161520-querkps",
                    "parentID": "",
                    "previousID": "",
                    "retData": null
                }
            ],
            "undoOperations": null
        }
    ]
}

action.data：更新块生成的 DOM

删除块

/api/block/deleteBlock

参数

{
    "id": "20211230161520-querkps"
}

id：待删除块的 ID

返回值

{
    "code": 0,
    "msg": "",
    "data": [
        {
            "doOperations": [
                {
                    "action": "delete",
                    "data": null,
                    "id": "20211230162439-vtm09qo",
                    "parentID": "",
                    "previousID": "",
                    "retData": null
                }
            ],
            "undoOperations": null
        }
    ]
}

移动块

/api/block/moveBlock

参数

{
    "id": "20230406180530-3o1rqkc",
    "previousID": "20230406152734-if5kyx6",
    "parentID": "20230404183855-woe52ko"
}

id：待移动块 ID

previousID：前一个块的 ID，用于锚定插入位置

parentID：父块的 ID，用于锚定插入位置，previousID 和 parentID 不能同时为空，同时存在的话优先使用 previousID

返回值

{
    "code": 0,
    "msg": "",
    "data": [
        {
            "doOperations": [
                {
                    "action": "move",
                    "data": null,
                    "id": "20230406180530-3o1rqkc",
                    "parentID": "20230404183855-woe52ko",
                    "previousID": "20230406152734-if5kyx6",
                    "nextID": "",
                    "retData": null,
                    "srcIDs": null,
                    "name": "",
                    "type": ""
                }
            ],
            "undoOperations": null
        }
    ]
}

获取块 kramdown 源码

/api/block/getBlockKramdown

参数

{
    "id": "20201225220955-l154bn4"
}

id：待获取块的 ID

返回值

{
    "code": 0,
    "msg": "",
    "data": {
        "id": "20201225220955-l154bn4",
        "kramdown": "* {: id=\"20201225220955-2nn1mns\"}新建笔记本，在笔记本下新建文档\n  {: id=\"20210131155408-3t627wc\"}\n* {: id=\"20201225220955-uwhqnug\"}在编辑器中输入 <kbd>/</kbd> 触发功能菜单\n  {: id=\"20210131155408-btnfw88\"}\n* {: id=\"20201225220955-04ymi2j\"}((20200813131152-0wk5akh \"在内容块中遨游\"))、((20200822191536-rm6hwid \"窗口和页签\"))\n  {: id=\"20210131155408-hh1z442\"}"
    }
}

获取子块

/api/block/getChildBlocks

参数

{
    "id": "20230506212712-vt9ajwj"
}

id：父块 ID

标题下方块也算作子块

返回值

{
    "code": 0,
    "msg": "",
    "data": [
        {
            "id": "20230512083858-mjdwkbn",
            "type": "h",
            "subType": "h1"
        },
        {
            "id": "20230513213727-thswvfd",
            "type": "s"
        },
        {
            "id": "20230513213633-9lsj4ew",
            "type": "l",
            "subType": "u"
        }
    ]
}

转移块引用

/api/block/transferBlockRef

参数

{
    "fromID": "20230612160235-mv6rrh1",
    "toID": "20230613093045-uwcomng",
    "refIDs": ["20230613092230-cpyimmd"]
}

fromID：定义块 ID

toID：目标块 ID

refIDs：指向定义块 ID 的引用所在块 ID，可选，如果不指定，所有指向定义块 ID 的引用块 ID 都会被转移

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

属性

设置块属性

/api/attr/setBlockAttrs

参数

{
    "id": "20210912214605-uhi5gco",
    "attrs": {
        "custom-attr1": "line1\nline2"
    }
}

id：块 ID

attrs：块属性，自定义属性必须以 custom- 作为前缀

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

获取块属性

/api/attr/getBlockAttrs

参数

{
    "id": "20210912214605-uhi5gco"
}

id：块 ID

返回值

{
    "code": 0,
    "msg": "",
    "data": {
        "custom-attr1": "line1\nline2",
        "id": "20210912214605-uhi5gco",
        "title": "PDF 标注双链演示",
        "type": "doc",
        "updated": "20210916120715"
    }
}

SQL

执行 SQL 查询

/api/query/sql

参数

{
    "stmt": "SELECT * FROM blocks WHERE content LIKE'%content%' LIMIT 7"
}

stmt：SQL 脚本

返回值

{
    "code": 0,
    "msg": "",
    "data": [{ "列": "值" }]
}

模板

渲染模板

/api/template/render

参数

{
    "id": "20220724223548-j6g0o87",
    "path": "F:\\SiYuan\\data\\templates\\foo.md"
}

id：调用渲染所在的文档 ID

path：模板文件绝对路径

返回值

{
    "code": 0,
    "msg": "",
    "data": {
        "content": "<div data-node-id=\"20220729234848-dlgsah7\" data-node-index=\"1\" data-type=\"NodeParagraph\" class=\"p\" updated=\"20220729234840\"><div contenteditable=\"true\" spellcheck=\"false\">foo</div><div class=\"protyle-attr\" contenteditable=\"false\"></div></div>",
        "path": "F:\\SiYuan\\data\\templates\\foo.md"
    }
}

渲染 Sprig

/api/template/renderSprig

参数

{
    "template": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}"
}

template：模板内容

返回值

{
    "code": 0,
    "msg": "",
    "data": "/daily note/2023/03/2023-03-24"
}

文件

获取文件

/api/file/getFile

参数

{
    "path": "/data/20210808180117-6v0mkxr/20200923234011-ieuun1p.sy"
}

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

返回值

文件内容

写入文件

/api/file/putFile

参数为 HTTP Multipart 表单

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

isDir：是否为创建文件夹，为 true 时仅创建文件夹，忽略 file

modTime：最近访问和修改时间，Unix time

file：上传的文件

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

删除文件

/api/file/removeFile

参数

{
    "path": "/data/20210808180117-6v0mkxr/20200923234011-ieuun1p.sy"
}

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

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

重命名文件

/api/file/renameFile

参数

{
    "path": "/data/assets/image-20230523085812-k3o9t32.png",
    "newPath": "/data/assets/test-20230523085812-k3o9t32.png"
}

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

newPath：新的文件路径

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

列出文件

/api/file/readDir

参数

{
    "path": "/data/20210808180117-6v0mkxr/20200923234011-ieuun1p.sy"
}

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

返回值

{
    "code": 0,
    "msg": "",
    "data": [
        {
            "isDir": true,
            "name": "20210808180320-abz7w6k"
        },
        {
            "isDir": false,
            "name": "20210808180320-abz7w6k.sy"
        }
    ]
}

导出

导出 Markdown 文本

/api/export/exportMdContent

参数

{
    "id": ""
}

id：要导出的文档块 ID

返回值

{
    "code": 0,
    "msg": "",
    "data": {
        "hPath": "/0 请从这里开始",
        "content": "## 🍫 内容块\n\n在思源中，唯一重要的核心概念是..."
    }
}

hPath：人类可读的路径

content：Markdown 内容

转换

Pandoc

/api/convert/pandoc

工作目录

执行调用 pandoc 命令时工作目录会被设置在 工作空间/temp/convert/pandoc/ 下

可先通过 API 写入文件 将待转换文件写入该目录

然后再调用该 API 进行转换，转换后的文件也会被写入该目录

最后调用 API 获取文件 获取转换后的文件内容

或者调用 API 通过 Markdown 创建文档

或者调用内部 API importStdMd 将转换后的文件夹直接导入

参数

{
    "args": ["--to", "markdown_strict-raw_html", "foo.epub", "-o", "foo.md"]
}

args：Pandoc 命令行参数

返回值

{
    "code": 0,
    "msg": "",
    "data": null
}

通知

推送消息

/api/notification/pushMsg

参数

{
    "msg": "test",
    "timeout": 7000
}

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

返回值

{
    "code": 0,
    "msg": "",
    "data": {
        "id": "62j1m2i"
    }
}

id：消息 ID

推送报错消息

/api/notification/pushErrMsg

参数

{
    "msg": "test",
    "timeout": 7000
}

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

返回值

{
    "code": 0,
    "msg": "",
    "data": {
        "id": "1q2c9z3"
    }
}

id：消息 ID

系统

获取启动进度

/api/system/bootProgress

不带参

返回值

{
    "code": 0,
    "msg": "",
    "data": {
        "details": "Finishing boot...",
        "progress": 100
    }
}

获取系统版本

/api/system/version

不带参

返回值

{
    "code": 0,
    "msg": "",
    "data": "1.3.5"
}

获取系统当前时间

/api/system/currentTime

不带参

返回值

{
    "code": 0,
    "msg": "",
    "data": 1631850968131
}

data: 精度为毫秒

说明#

API 调用格式#

样例代码#

API 大纲#

笔记本#

列出笔记本#

打开笔记本#

关闭笔记本#

重命名笔记本#

创建笔记本#

删除笔记本#

获取笔记本配置#

保存笔记本配置#

文档#

通过 Markdown 创建文档#

重命名文档#

删除文档#

移动文档#

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

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

资源文件#

上传资源文件#

块#

插入块#

插入前置子块#

插入后置子块#

更新块#

删除块#

移动块#

获取块 kramdown 源码#

获取子块#

转移块引用#

属性#

设置块属性#

获取块属性#

SQL#

执行 SQL 查询#

模板#

渲染模板#

渲染 Sprig#

文件#

获取文件#

写入文件#

删除文件#

重命名文件#

列出文件#

导出#

导出 Markdown 文本#

转换#

Pandoc#

通知#

推送消息#

推送报错消息#

系统#

获取启动进度#

获取系统版本#

获取系统当前时间#

说明

API 调用格式

样例代码

API 大纲

笔记本

列出笔记本

打开笔记本

关闭笔记本

重命名笔记本

创建笔记本

删除笔记本

获取笔记本配置

保存笔记本配置

文档

通过 Markdown 创建文档

重命名文档

删除文档

移动文档

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

根据 ID 获取人类可读路径

资源文件

上传资源文件

块

插入块

插入前置子块

插入后置子块

更新块

删除块

移动块

获取块 kramdown 源码

获取子块

转移块引用

属性

设置块属性

获取块属性

SQL

执行 SQL 查询

模板

渲染模板

渲染 Sprig

文件

获取文件

写入文件

删除文件

重命名文件

列出文件

导出

导出 Markdown 文本

转换

Pandoc

通知

推送消息

推送报错消息

系统

获取启动进度

获取系统版本

获取系统当前时间