端点:http://127.0.0.1:6806
均是 POST 方法
需要带参的接口,参数为 JSON 字符串,放置到 body 里,标头 Content-Type 为 application/json
返回值
{
"code": 0,
"msg": "",
"data": {}
}
code
:非 0 为异常情况msg
:正常情况下是空字符串,异常情况下会返回错误文案data
:可能为 {}
、[]
或者 NULL
,根据不同接口而不同在 设置 - 关于 里查看 API token,请求标头:Authorization: Token xxx
/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": ""
}
}
/api/filetree/createDocWithMd
参数
{
"notebook": "20210817205410-2kvfpfn",
"path": "/foo/bar",
"markdown": ""
}
notebook
:笔记本 IDpath
:文档路径,需要以 / 开头,中间使用 / 分隔层级(这里的 path 对应数据库 hpath 字段)markdown
:GFM Markdown 内容返回值
{
"code": 0,
"msg": "",
"data": "20210914223645-oj2vnx2"
}
data
:创建好的文档 IDpath
重复调用该接口,不会覆盖已有文档/api/filetree/renameDoc
参数
{
"notebook": "20210831090520-7dvbdv0",
"path": "/20210902210113-0avi12f.sy",
"title": "文档新标题"
}
notebook
:笔记本 IDpath
:文档路径返回值
{
"code": 0,
"msg": "",
"data": null
}
/api/filetree/removeDoc
参数
{
"notebook": "20210831090520-7dvbdv0",
"path": "/20210902210113-0avi12f.sy"
}
notebook
:笔记本 IDpath
:文档路径返回值
{
"code": 0,
"msg": "",
"data": null
}
/api/filetree/moveDocs
参数
{
"fromPaths": ["/20210917220056-yxtyl7i.sy"],
"toNotebook": "20210817205410-2kvfpfn",
"toPath": "/"
}
fromPaths
:源路径toNotebook
:目标笔记本 IDtoPath
:目标路径返回值
{
"code": 0,
"msg": "",
"data": null
}
/api/filetree/getHPathByPath
参数
{
"notebook": "20210831090520-7dvbdv0",
"path": "/20210917220500-sz588nq/20210917220056-yxtyl7i.sy"
}
notebook
:笔记本 IDpath
:路径返回值
{
"code": 0,
"msg": "",
"data": "/foo/bar"
}
/api/filetree/getHPathByID
参数
{
"id": "20210917220056-yxtyl7i"
}
id
:块 ID返回值
{
"code": 0,
"msg": "",
"data": "/foo/bar"
}
/api/filetree/getIDsByHPath
参数
{
"path": "/foo/bar",
"notebook": "20210808180117-czj9bvb"
}
path
:人类可读路径notebook
:笔记本 ID返回值
{
"code": 0,
"msg": "",
"data": [
"20200813004931-q4cu8na"
]
}
/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
:新插入块生成的 DOMaction.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
:新插入块生成的 DOMaction.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
:新插入块生成的 DOMaction.id
:新插入块的 ID/api/block/updateBlock
参数
{
"dataType": "markdown",
"data": "foobarbaz",
"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
:待移动块 IDpreviousID
:前一个块的 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
}
]
}
/api/block/foldBlock
参数
{
"id": "20231224160424-2f5680o"
}
id
:待折叠块的 ID返回值
{
"code": 0,
"msg": "",
"data": null
}
/api/block/unfoldBlock
参数
{
"id": "20231224160424-2f5680o"
}
id
:待展开块的 ID返回值
{
"code": 0,
"msg": "",
"data": null
}
/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
:定义块 IDtoID
:目标块 IDrefIDs
:指向定义块 ID 的引用所在块 ID,可选,如果不指定,所有指向定义块 ID 的块引用 ID 都会被转移返回值
{
"code": 0,
"msg": "",
"data": null
}
/api/attr/setBlockAttrs
参数
{
"id": "20210912214605-uhi5gco",
"attrs": {
"custom-attr1": "line1\nline2"
}
}
id
:块 IDattrs
:块属性,自定义属性必须以 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"
}
}
/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
:调用渲染所在的文档 IDpath
:模板文件绝对路径返回值
{
"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"
}
}
/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
:工作空间路径下的文件路径返回值
响应状态码 200
: 文件内容
响应状态码 202
: 异常信息
{
"code": 404,
"msg": "",
"data": null
}
code
: 非零的异常值
-1
: 参数解析错误403
: 无访问权限 (文件不在工作空间下)404
: 未找到 (文件不存在)405
: 方法不被允许 (这是一个目录)500
: 服务器错误 (文件查询失败 / 文件读取失败)msg
: 一段描述错误的文本
/api/file/putFile
参数为 HTTP Multipart 表单
path
:工作空间路径下的文件路径isDir
:是否为创建文件夹,为 true
时仅创建文件夹,忽略 file
modTime
:最近访问和修改时间,Unix timefile
:上传的文件返回值
{
"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"
}
path
:工作空间路径下的文件夹路径返回值
{
"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
参数
{
"id": ""
}
id
:要导出的文档块 ID返回值
{
"code": 0,
"msg": "",
"data": {
"hPath": "/0 请从这里开始",
"content": "## 🍫 内容块\n\n在思源中,唯一重要的核心概念是..."
}
}
hPath
:人类可读的路径content
:Markdown 内容/api/export/exportResources
参数
{
"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
返回值
{
"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
工作目录
工作空间/temp/convert/pandoc/${test}
下写入文件
将待转换文件写入该目录获取文件
获取转换后的文件内容
通过 Markdown 创建文档
importStdMd
将转换后的文件夹直接导入参数
{
"dir": "test",
"args": [
"--to", "markdown_strict-raw_html",
"foo.epub",
"-o", "foo.md"
]
}
args
:Pandoc 命令行参数返回值
{
"code": 0,
"msg": "",
"data": {
"path": "/temp/convert/pandoc/test"
}
}
path
:工作空间下的路径/api/notification/pushMsg
参数
{
"msg": "test",
"timeout": 7000
}
timeout
:消息持续显示时间,单位为毫秒。可以不传入该字段,默认为 7000 毫秒返回值
{
"code": 0,
"msg": "",
"data": {
"id": "62jtmqi"
}
}
id
:消息 ID/api/notification/pushErrMsg
参数
{
"msg": "test",
"timeout": 7000
}
timeout
:消息持续显示时间,单位为毫秒。可以不传入该字段,默认为 7000 毫秒返回值
{
"code": 0,
"msg": "",
"data": {
"id": "qc9znut"
}
}
id
:消息 ID/api/network/forwardProxy
参数
{
"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
返回值
{
"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
不带参
返回值
{
"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
: 精度为毫秒此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。