思源后端 API 文档

规范

参数和返回值

鉴权

笔记本

端点：http://127.0.0.1:6806

均是 POST 方法

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

返回值

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

code：非 0 为异常情况

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

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

/api/notebook/lsNotebooks

不带参

返回值

          json
          
        
{
  "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

参数

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

notebook：笔记本 ID

返回值

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

/api/notebook/closeNotebook

参数

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

notebook：笔记本 ID

返回值

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

/api/notebook/renameNotebook

参数

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

notebook：笔记本 ID

返回值

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

/api/notebook/createNotebook

参数

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

返回值

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

/api/notebook/removeNotebook

参数

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

notebook：笔记本 ID

返回值

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

/api/notebook/getNotebookConf

参数

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

notebook：笔记本 ID

返回值

          json
          
        
{
  "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

参数

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

notebook：笔记本 ID

返回值

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

/api/filetree/createDocWithMd

参数

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

notebook：笔记本 ID

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

markdown：GFM Markdown 内容

返回值

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

data：创建好的文档 ID

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

/api/filetree/renameDoc

参数

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

notebook：笔记本 ID

path：文档路径

返回值

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

/api/filetree/removeDoc

参数

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

notebook：笔记本 ID

path：文档路径

返回值

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

/api/filetree/moveDocs

参数

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

fromPaths：源路径

toNotebook：目标笔记本 ID

toPath：目标路径

返回值

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

/api/filetree/getHPathByPath

参数

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

notebook：笔记本 ID

path：路径

返回值

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

/api/filetree/getHPathByID

参数

          json
          
        
{
  "id": "20210917220056-yxtyl7i"
}

id：块 ID

返回值

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

/api/filetree/getIDsByHPath

参数

          json
          
        
{
  "path": "/foo/bar",
  "notebook": "20210808180117-czj9bvb"
}

path：人类可读路径

notebook：笔记本 ID

返回值

          json
          
        
{
  "code": 0,
  "msg": "",
  "data": [
      "20200813004931-q4cu8na"
  ]
}

/api/asset/upload

参数为 HTTP Multipart 表单

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

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

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

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

file[]：上传的文件列表

返回值

          json
          
        
{
  "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

参数

          json
          
        
{
  "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

返回值

          json
          
        
{
  "code": 0,
  "msg": "",
  "data": [
    {
      "doOperations": [
        {
          "action": "insert",
          "data": "foobarbaz
",
          "id": "20211230115020-g02dfx0",
          "parentID": "",
          "previousID": "20211229114650-vrek5x6",
          "retData": null
        }
      ],
      "undoOperations": null
    }
  ]
}

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

action.id：新插入块的 ID

/api/block/prependBlock

参数

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

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

data：待插入的数据

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

返回值

          json
          
        
{
  "code": 0,
  "msg": "",
  "data": [
    {
      "doOperations": [
        {
          "action": "insert",
          "data": "foobarbaz
",
          "id": "20220108003710-hm0x9sc",
          "parentID": "20220107173950-7f9m1nb",
          "previousID": "",
          "retData": null
        }
      ],
      "undoOperations": null
    }
  ]
}

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

action.id：新插入块的 ID

/api/block/appendBlock

参数

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

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

data：待插入的数据

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

返回值

          json
          
        
{
  "code": 0,
  "msg": "",
  "data": [
    {
      "doOperations": [
        {
          "action": "insert",
          "data": "foobarbaz
",
          "id": "20220108003642-y2wmpcv",
          "parentID": "20220107173950-7f9m1nb",
          "previousID": "20220108003615-7rk41t1",
          "retData": null
        }
      ],
      "undoOperations": null
    }
  ]
}

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

action.id：新插入块的 ID

/api/block/updateBlock

参数

          json
          
        
{
  "dataType": "markdown",
  "data": "foobarbaz",
  "id": "20211230161520-querkps"
}

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

data：待更新的数据

id：待更新块的 ID

返回值

          json
          
        
{
  "code": 0,
  "msg": "",
  "data": [
    {
      "doOperations": [
        {
          "action": "update",
          "data": "foobarbaz
",
          "id": "20211230161520-querkps",
          "parentID": "",
          "previousID": "",
          "retData": null
          }
        ],
      "undoOperations": null
    }
  ]
}

action.data：更新块生成的 DOM

/api/block/deleteBlock

参数

          json
          
        
{
  "id": "20211230161520-querkps"
}

id：待删除块的 ID

返回值

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

/api/block/moveBlock

参数

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

id：待移动块 ID

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

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

返回值

          json
          
        
{
  "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
      }
  ]
}

/api/block/foldBlock

参数

          json
          
        
{
  "id": "20231224160424-2f5680o"
}

id：待折叠块的 ID

返回值

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

/api/block/unfoldBlock

参数

          json
          
        
{
  "id": "20231224160424-2f5680o"
}

id：待展开块的 ID

返回值

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

/api/block/getBlockKramdown

参数

          json
          
        
{
  "id": "20201225220955-l154bn4"
}

id：待获取块的 ID

返回值

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

/api/block/getChildBlocks

参数

          json
          
        
{
  "id": "20230506212712-vt9ajwj"
}

id：父块 ID

标题下方块也算作子块

返回值

          json
          
        
{
  "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

参数

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

fromID：定义块 ID

toID：目标块 ID

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

返回值

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

/api/attr/setBlockAttrs

参数

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

id：块 ID

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

返回值

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

/api/attr/getBlockAttrs

参数

          json
          
        
{
  "id": "20210912214605-uhi5gco"
}

id：块 ID

返回值

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

/api/query/sql

参数

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

stmt：SQL 脚本

返回值

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

/api/template/render

参数

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

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

path：模板文件绝对路径

返回值

          json
          
        
{
  "code": 0,
  "msg": "",
  "data": {
    "content": "foo​
",
    "path": "F:\\SiYuan\\data\\templates\\foo.md"
  }
}

/api/template/renderSprig

参数

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

template：模板内容

返回值

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

/api/file/getFile

参数

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

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

返回值

响应状态码 200: 文件内容

响应状态码 202: 异常信息

          json
          
        
{
  "code": 404,
  "msg": "",
  "data": null
}

code: 非零的异常值

-1: 参数解析错误

403: 无访问权限 (文件不在工作空间下)

404: 未找到 (文件不存在)

405: 方法不被允许 (这是一个目录)

500: 服务器错误 (文件查询失败 / 文件读取失败)

msg: 一段描述错误的文本

/api/file/putFile

参数为 HTTP Multipart 表单

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

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

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

file：上传的文件

返回值

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

/api/file/removeFile

参数

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

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

返回值

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

/api/file/renameFile

参数

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

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

newPath：新的文件路径

返回值

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

/api/file/readDir

参数

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

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

返回值

          json
          
        
{
  "code": 0,
  "msg": "",
  "data": [
    {
      "isDir": true,
      "isSymlink": false,
      "name": "20210808180303-6yi0dv5",
      "updated": 1691467624
    },
    {
      "isDir": false,
      "isSymlink": false,
      "name": "20210808180303-6yi0dv5.sy",
      "updated": 1663298365
    }
  ]
}

/api/export/exportMdContent

参数

          json
          
        
{
  "id": ""
}

id：要导出的文档块 ID

返回值

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

hPath：人类可读的路径

content：Markdown 内容

/api/export/exportResources

参数

          json
          
        
{
  "paths": [
    "/conf/appearance/boot",
    "/conf/appearance/langs",
    "/conf/appearance/emojis/conf.json",
    "/conf/appearance/icons/index.html"
  ],
  "name": "zip-file-name"
}

paths：要导出的文件或文件夹路径列表，相同名称的文件/文件夹会被覆盖

name：（可选）导出的文件名，未设置时默认为 export-YYYY-MM-DD_hh-mm-ss.zip

返回值

          json
          
        
{
  "code": 0,
  "msg": "",
  "data": {
    "path": "temp/export/zip-file-name.zip"
  }
}

path：创建的 *.zip 文件路径

zip-file-name.zip 中的目录结构如下所示：

zip-file-name

boot

langs

conf.json

index.html

/api/convert/pandoc

工作目录

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

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

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

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

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

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

参数

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

args：Pandoc 命令行参数

返回值

          json
          
        
{
  "code": 0,
  "msg": "",
  "data": {
     "path": "/temp/convert/pandoc/test"
  }
}

path：工作空间下的路径

/api/notification/pushMsg

参数

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

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

返回值

          json
          
        
{
  "code": 0,
  "msg": "",
  "data": {
      "id": "62jtmqi"
  }
}

id：消息 ID

/api/notification/pushErrMsg

参数

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

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

返回值

          json
          
        
{
  "code": 0,
  "msg": "",
  "data": {
      "id": "qc9znut"
  }
}

id：消息 ID

/api/network/forwardProxy

参数

          json
          
        
{
  "url": "https://b3log.org/siyuan/",
  "method": "GET",
  "timeout": 7000,
  "contentType": "text/html",
  "headers": [
      {
          "Cookie": ""
      }
  ],
  "payload": {},
  "payloadEncoding": "text",
  "responseEncoding": "text"
}

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

返回值

          json
          
        
{
  "code": 0,
  "msg": "",
  "data": {
    "body": "",
    "bodyEncoding": "text",
    "contentType": "text/html",
    "elapsed": 1976,
    "headers": {
    },
    "status": 200,
    "url": "https://b3log.org/siyuan"
  }
}

bodyEncoding：body 所使用的编码方案，与请求中 responseEncoding 字段一致，默认为 text，可能的值如下所示

text

base64 | base64-std

base64-url

base32 | base32-std

base32-hex

hex

/api/system/bootProgress

不带参

返回值

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

/api/system/version

不带参

返回值

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

/api/system/currentTime

不带参

返回值

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

data: 精度为毫秒

Wilson@思源

思源后端 API 文档

规范

参数和返回值

鉴权

笔记本

列出笔记本

打开笔记本

关闭笔记本

重命名笔记本

创建笔记本

删除笔记本

获取笔记本配置

保存笔记本配置

文档

通过 Markdown 创建文档

重命名文档

删除文档

移动文档

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

根据 ID 获取人类可读路径

根据人类可读路径获取 IDs

资源文件

上传资源文件

块

插入块

插入前置子块

插入后置子块

更新块

删除块

移动块

折叠块

展开块

获取块 kramdown 源码

获取子块

转移块引用

属性

设置块属性

获取块属性

SQL

执行 SQL 查询

模板

渲染模板

渲染 Sprig

文件

获取文件

写入文件

删除文件

重命名文件

列出文件

导出

导出 Markdown 文本

导出文件与目录

转换

Pandoc

通知

推送消息

推送报错消息

网络

正向代理

系统

获取启动进度

获取系统版本

获取系统当前时间