- Specification
- Notebooks
- Documents
- Assets
- Blocks
- Attributes
- SQL
- Templates
- File
- Export
- Conversion
- Notification
- Network
- System
-
Endpoint:
http://127.0.0.1:6806
-
Both are POST methods
-
An interface with parameters is required, the parameter is a JSON string, placed in the body, and the header Content-Type is
application/json
-
Return value
{ "code": 0, "msg": "", "data": {} }
code
: non-zero for exceptionsmsg
: an empty string under normal circumstances, an error text will be returned under abnormal conditionsdata
: may be{}
,[]
orNULL
, depending on the interface
View API token in Settings - About, request header: Authorization: Token xxx
-
/api/notebook/lsNotebooks
-
No parameters
-
Return value
{ "code": 0, "msg": "", "data": { "notebooks": [ { "id": "20210817205410-2kvfpfn", "name": "Test Notebook", "icon": "1f41b", "sort": 0, "closed": false }, { "id": "20210808180117-czj9bvb", "name": "SiYuan User Guide", "icon": "1f4d4", "sort": 1, "closed": false } ] } }
-
/api/notebook/openNotebook
-
Parameters
{ "notebook": "20210831090520-7dvbdv0" }
notebook
: Notebook ID
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/notebook/closeNotebook
-
Parameters
{ "notebook": "20210831090520-7dvbdv0" }
notebook
: Notebook ID
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/notebook/renameNotebook
-
Parameters
{ "notebook": "20210831090520-7dvbdv0", "name": "New name for notebook" }
notebook
: Notebook ID
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/notebook/createNotebook
-
Parameters
{ "name": "Notebook name" }
-
Return value
{ "code": 0, "msg": "", "data": { "notebook": { "id": "20220126215949-r1wvoch", "name": "Notebook name", "icon": "", "sort": 0, "closed": false } } }
-
/api/notebook/removeNotebook
-
Parameters
{ "notebook": "20210831090520-7dvbdv0" }
notebook
: Notebook ID
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/notebook/getNotebookConf
-
Parameters
{ "notebook": "20210817205410-2kvfpfn" }
notebook
: Notebook ID
-
Return value
{ "code": 0, "msg": "", "data": { "box": "20210817205410-2kvfpfn", "conf": { "name": "Test Notebook", "closed": false, "refCreateSavePath": "", "createDocNameTemplate": "", "dailyNoteSavePath": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}", "dailyNoteTemplatePath": "" }, "name": "Test Notebook" } }
-
/api/notebook/setNotebookConf
-
Parameters
{ "notebook": "20210817205410-2kvfpfn", "conf": { "name": "Test Notebook", "closed": false, "refCreateSavePath": "", "createDocNameTemplate": "", "dailyNoteSavePath": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}", "dailyNoteTemplatePath": "" } }
notebook
: Notebook ID
-
Return value
{ "code": 0, "msg": "", "data": { "name": "Test Notebook", "closed": false, "refCreateSavePath": "", "createDocNameTemplate": "", "dailyNoteSavePath": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}", "dailyNoteTemplatePath": "" } }
-
/api/filetree/createDocWithMd
-
Parameters
{ "notebook": "20210817205410-2kvfpfn", "path": "/foo/bar", "markdown": "" }
notebook
: Notebook IDpath
: Document path, which needs to start with / and separate levels with / (path here corresponds to the database hpath field)markdown
: GFM Markdown content
-
Return value
{ "code": 0, "msg": "", "data": "20210914223645-oj2vnx2" }
data
: Created document ID- If you use the same
path
to call this interface repeatedly, the existing document will not be overwritten
-
/api/filetree/renameDoc
-
Parameters
{ "notebook": "20210831090520-7dvbdv0", "path": "/20210902210113-0avi12f.sy", "title": "Document new title" }
notebook
: Notebook IDpath
: Document path
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/filetree/removeDoc
-
Parameters
{ "notebook": "20210831090520-7dvbdv0", "path": "/20210902210113-0avi12f.sy" }
notebook
: Notebook IDpath
: Document path
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/filetree/moveDocs
-
Parameters
{ "fromPaths": ["/20210917220056-yxtyl7i.sy"], "toNotebook": "20210817205410-2kvfpfn", "toPath": "/" }
fromPaths
: Source pathstoNotebook
: Target notebook IDtoPath
: Target path
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/filetree/getHPathByPath
-
Parameters
{ "notebook": "20210831090520-7dvbdv0", "path": "/20210917220500-sz588nq/20210917220056-yxtyl7i.sy" }
notebook
: Notebook IDpath
: Document path
-
Return value
{ "code": 0, "msg": "", "data": "/foo/bar" }
-
/api/filetree/getHPathByID
-
Parameters
{ "id": "20210917220056-yxtyl7i" }
id
: Block ID
-
Return value
{ "code": 0, "msg": "", "data": "/foo/bar" }
-
/api/filetree/getIDsByHPath
-
Parameters
{ "path": "/foo/bar", "notebook": "20210808180117-czj9bvb" }
path
: Human-readable pathnotebook
: Notebook ID
-
Return value
{ "code": 0, "msg": "", "data": [ "20200813004931-q4cu8na" ] }
-
/api/asset/upload
-
The parameter is an HTTP Multipart form
-
assetsDirPath
: The folder path where assets are stored, with the data folder as the root path, for example:"/assets/"
: workspace/data/assets/ folder"/assets/sub/"
: workspace/data/assets/sub/ folder
Under normal circumstances, it is recommended to use the first method, which is stored in the assets folder of the workspace, putting in a subdirectory has some side effects, please refer to the assets chapter of the user guide.
-
file[]
: Uploaded file list
-
-
Return value
{ "code": 0, "msg": "", "data": { "errFiles": [""], "succMap": { "foo.png": "assets/foo-20210719092549-9j5y79r.png" } } }
errFiles
: List of filenames with errors in upload processingsuccMap
: For successfully processed files, the key is the file name when uploading, and the value is assets/foo-id.png, which is used to replace the asset link address in the existing Markdown content with the uploaded address
-
/api/block/insertBlock
-
Parameters
{ "dataType": "markdown", "data": "foo**bar**{: style=\"color: var(--b3-font-color8);\"}baz", "nextID": "", "previousID": "20211229114650-vrek5x6", "parentID": "" }
dataType
: The data type to be inserted, the value can bemarkdown
ordom
data
: Data to be insertednextID
: The ID of the next block, used to anchor the insertion positionpreviousID
: The ID of the previous block, used to anchor the insertion positionparentID
: The ID of the parent block, used to anchor the insertion position
nextID
,previousID
, andparentID
must have at least one value, using priority:nextID
>previousID
>parentID
-
Return value
{ "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 generated by the newly inserted blockaction.id
: ID of the newly inserted block
-
/api/block/prependBlock
-
Parameters
{ "data": "foo**bar**{: style=\"color: var(--b3-font-color8);\"}baz", "dataType": "markdown", "parentID": "20220107173950-7f9m1nb" }
dataType
: The data type to be inserted, the value can bemarkdown
ordom
data
: Data to be insertedparentID
: The ID of the parent block, used to anchor the insertion position
-
Return value
{ "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 generated by the newly inserted blockaction.id
: ID of the newly inserted block
-
/api/block/appendBlock
-
Parameters
{ "data": "foo**bar**{: style=\"color: var(--b3-font-color8);\"}baz", "dataType": "markdown", "parentID": "20220107173950-7f9m1nb" }
dataType
: The data type to be inserted, the value can bemarkdown
ordom
data
: Data to be insertedparentID
: The ID of the parent block, used to anchor the insertion position
-
Return value
{ "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 generated by the newly inserted blockaction.id
: ID of the newly inserted block
-
/api/block/updateBlock
-
Parameters
{ "dataType": "markdown", "data": "foobarbaz", "id": "20211230161520-querkps" }
dataType
: The data type to be updated, the value can bemarkdown
ordom
data
: Data to be updatedid
: ID of the block to be updated
-
Return value
{ "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 generated by the updated block
-
/api/block/deleteBlock
-
Parameters
{ "id": "20211230161520-querkps" }
id
: ID of the block to be deleted
-
Return value
{ "code": 0, "msg": "", "data": [ { "doOperations": [ { "action": "delete", "data": null, "id": "20211230162439-vtm09qo", "parentID": "", "previousID": "", "retData": null } ], "undoOperations": null } ] }
-
/api/block/moveBlock
-
Parameters
{ "id": "20230406180530-3o1rqkc", "previousID": "20230406152734-if5kyx6", "parentID": "20230404183855-woe52ko" }
id
: Block ID to movepreviousID
: The ID of the previous block, used to anchor the insertion positionparentID
: The ID of the parent block, used to anchor the insertion position,previousID
andparentID
cannot be empty at the same time, if they exist at the same time,previousID
will be used first
-
Return value
{ "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
-
Parameters
{ "id": "20231224160424-2f5680o" }
id
: Block ID to fold
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/block/unfoldBlock
-
Parameters
{ "id": "20231224160424-2f5680o" }
id
: Block ID to unfold
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/block/getBlockKramdown
-
Parameters
{ "id": "20201225220954-dlgzk1o" }
id
: ID of the block to be got
-
Return value
{ "code": 0, "msg": "", "data": { "id": "20201225220954-dlgzk1o", "kramdown": "* {: id=\"20201225220954-e913snx\"}Create a new notebook, create a new document under the notebook\n {: id=\"20210131161940-kfs31q6\"}\n* {: id=\"20201225220954-ygz217h\"}Enter <kbd>/</kbd> in the editor to trigger the function menu\n {: id=\"20210131161940-eo0riwq\"}\n* {: id=\"20201225220954-875yybt\"}((20200924101200-gss5vee \"Navigate in the content block\")) and ((20200924100906-0u4zfq3 \"Window and tab\"))\n {: id=\"20210131161940-b5uow2h\"}" } }
-
/api/block/getChildBlocks
-
Parameters
{ "id": "20230506212712-vt9ajwj" }
id
: Parent block ID- The blocks below a heading are also counted as child blocks
-
Return value
{ "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
-
Parameters
{ "fromID": "20230612160235-mv6rrh1", "toID": "20230613093045-uwcomng", "refIDs": ["20230613092230-cpyimmd"] }
fromID
: Def block IDtoID
: Target block IDrefIDs
: Ref block IDs point to def block ID, optional, if not specified, all ref block IDs will be transferred
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/attr/setBlockAttrs
-
Parameters
{ "id": "20210912214605-uhi5gco", "attrs": { "custom-attr1": "line1\nline2" } }
id
: Block IDattrs
: Block attributes, custom attributes must be prefixed withcustom-
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/attr/getBlockAttrs
-
Parameters
{ "id": "20210912214605-uhi5gco" }
id
: Block ID
-
Return value
{ "code": 0, "msg": "", "data": { "custom-attr1": "line1\nline2", "id": "20210912214605-uhi5gco", "title": "PDF Annotation Demo", "type": "doc", "updated": "20210916120715" } }
-
/api/query/sql
-
Parameters
{ "stmt": "SELECT * FROM blocks WHERE content LIKE'%content%' LIMIT 7" }
stmt
: SQL statement
-
Return value
{ "code": 0, "msg": "", "data": [ { "col": "val" } ] }
-
/api/template/render
-
Parameters
{ "id": "20220724223548-j6g0o87", "path": "F:\\SiYuan\\data\\templates\\foo.md" }
id
: The ID of the document where the rendering is calledpath
: Template file absolute path
-
Return value
{ "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
-
Parameters
{ "template": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}" }
template
: template content
-
Return value
{ "code": 0, "msg": "", "data": "/daily note/2023/03/2023-03-24" }
-
/api/file/getFile
-
Parameters
json { "path": "/data/20210808180117-6v0mkxr/20200923234011-ieuun1p.sy" }
path
: the file path under the workspace path
-
Return value
-
Response status code
200
: File content -
Response status code
202
: Exception information{ "code": 404, "msg": "", "data": null }
-
code
: non-zero for exceptions-1
: Parameter parsing error403
: Permission denied (file is not in the workspace)404
: Not Found (file doesn't exist)405
: Method Not Allowed (it's a directory)500
: Server Error (stat file failed / read file failed)
-
msg
: a piece of text describing the error
-
-
-
/api/file/putFile
-
The parameter is an HTTP Multipart form
path
: the file path under the workspace pathisDir
: whether to create a folder, whentrue
only create a folder, ignorefile
modTime
: last access and modification time, Unix timefile
: the uploaded file
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/file/removeFile
-
Parameters
{ "path": "/data/20210808180117-6v0mkxr/20200923234011-ieuun1p.sy" }
path
: the file path under the workspace path
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/file/renameFile
-
Parameters
{ "path": "/data/assets/image-20230523085812-k3o9t32.png", "newPath": "/data/assets/test-20230523085812-k3o9t32.png" }
path
: the file path under the workspace pathnewPath
: the new file path under the workspace path
-
Return value
{ "code": 0, "msg": "", "data": null }
-
/api/file/readDir
-
Parameters
{ "path": "/data/20210808180117-6v0mkxr/20200923234011-ieuun1p" }
path
: the dir path under the workspace path
-
Return value
{ "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
-
Parameters
{ "id": "" }
id
: ID of the doc block to export
-
Return value
{ "code": 0, "msg": "", "data": { "hPath": "/Please Start Here", "content": "## 🍫 Content Block\n\nIn SiYuan, the only important core concept is..." } }
hPath
: human-readable pathcontent
: Markdown content
-
/api/export/exportResources
-
Parameters
{ "paths": [ "/conf/appearance/boot", "/conf/appearance/langs", "/conf/appearance/emojis/conf.json", "/conf/appearance/icons/index.html" ], "name": "zip-file-name" }
paths
: A list of file or folder paths to be exported, the same filename/folder name will be overwrittenname
: (Optional) The exported file name, which defaults toexport-YYYY-MM-DD_hh-mm-ss.zip
when not set
-
Return value
{ "code": 0, "msg": "", "data": { "path": "temp/export/zip-file-name.zip" } }
path
: The path of*.zip
file created- The directory structure in
zip-file-name.zip
is as follows:zip-file-name
boot
langs
conf.json
index.html
- The directory structure in
-
/api/convert/pandoc
-
Working directory
- Executing the pandoc command will set the working directory to
workspace/temp/convert/pandoc/${dir}
- API
Put file
can be used to write the file to be converted to this directory first - Then call the API for conversion, and the converted file will also be written to this directory
- Finally, call the API
Get file
to get the converted file- Or call the API Create a document with Markdown
- Or call the internal API
importStdMd
to import the converted folder directly
- Executing the pandoc command will set the working directory to
-
Parameters
{ "dir": "test", "args": [ "--to", "markdown_strict-raw_html", "foo.epub", "-o", "foo.md" ] }
args
: Pandoc command line parameters
-
Return value
{ "code": 0, "msg": "", "data": { "path": "/temp/convert/pandoc/test" } }
path
: the path under the workspace
-
/api/notification/pushMsg
-
Parameters
{ "msg": "test", "timeout": 7000 }
timeout
: The duration of the message display in milliseconds. This field can be omitted, the default is 7000 milliseconds
-
Return value
{ "code": 0, "msg": "", "data": { "id": "62jtmqi" } }
id
: Message ID
-
/api/notification/pushErrMsg
-
Parameters
{ "msg": "test", "timeout": 7000 }
timeout
: The duration of the message display in milliseconds. This field can be omitted, the default is 7000 milliseconds
-
Return value
{ "code": 0, "msg": "", "data": { "id": "qc9znut" } }
id
: Message ID
-
/api/network/forwardProxy
-
Parameters
{ "url": "https://b3log.org/siyuan/", "method": "GET", "timeout": 7000, "contentType": "text/html", "headers": [ { "Cookie": "" } ], "payload": {}, "payloadEncoding": "text", "responseEncoding": "text" }
-
url
: URL to forward -
method
: HTTP method, default isPOST
-
timeout
: timeout in milliseconds, default is7000
-
contentType
: Content-Type, default isapplication/json
-
headers
: HTTP headers -
payload
: HTTP payload, object or string -
payloadEncoding
: The encoding scheme used bypyaload
, default istext
, optional values are as followstext
base64
|base64-std
base64-url
base32
|base32-std
base32-hex
hex
-
responseEncoding
: The encoding scheme used bybody
in response data, default istext
, optional values are as followstext
base64
|base64-std
base64-url
base32
|base32-std
base32-hex
hex
-
-
Return value
{ "code": 0, "msg": "", "data": { "body": "", "bodyEncoding": "text", "contentType": "text/html", "elapsed": 1976, "headers": { }, "status": 200, "url": "https://b3log.org/siyuan" } }
-
bodyEncoding
: The encoding scheme used bybody
, is consistent with fieldresponseEncoding
in request, default istext
, optional values are as followstext
base64
|base64-std
base64-url
base32
|base32-std
base32-hex
hex
-
-
/api/system/bootProgress
-
No parameters
-
Return value
{ "code": 0, "msg": "", "data": { "details": "Finishing boot...", "progress": 100 } }
-
/api/system/version
-
No parameters
-
Return value
{ "code": 0, "msg": "", "data": "1.3.5" }
-
/api/system/currentTime
-
No parameters
-
Return value
{ "code": 0, "msg": "", "data": 1631850968131 }
data
: Precision in milliseconds