* [Specification](#Specification) * [Parameters and return values](#Parameters-and-return-values) * [鉴权](#鉴权) * [笔记本](#笔记本) * [列出笔记本](#列出笔记本) * [打开笔记本](#打开笔记本) * [关闭笔记本](#关闭笔记本) * [重命名笔记本](#重命名笔记本) * [创建笔记本](#创建笔记本) * [删除笔记本](#删除笔记本) * [获取笔记本配置](#获取笔记本配置) * [保存笔记本配置](#保存笔记本配置) * [文档](#文档) * [通过 Markdown 创建文档](#通过-markdown-创建文档) * [重命名文档](#重命名文档) * [删除文档](#删除文档) * [移动文档](#移动文档) * [根据路径获取人类可读路径](#根据路径获取人类可读路径) * [资源文件](#资源文件) * [上传资源文件](#上传资源文件) * [块操作](#块操作) * [插入块](#插入块) * [插入前置子块](#插入前置子块) * [插入后置子块](#插入后置子块) * [更新块](#更新块) * [删除块](#删除块) * [属性](#属性) * [设置块属性](#设置块属性) * [获取块属性](#获取块属性) * [SQL](#SQL) * [SQL 查询](#SQL-查询) * [模板](#模板) * [渲染模板](#渲染模板) * [导出](#导出) * [导出 Markdown 文本](#导出-markdown-文本) * [系统](#系统) * [获取启动进度](#获取启动进度) * [获取系统版本](#获取系统版本) * [获取系统当前时间](#获取系统当前时间) * [Webhook](#Webhook) --- ## Specification ### Parameters and return values * 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 ````json { "code": 0, "msg": "", "data": {} } ```` * `code`: non-zero for exceptions * `msg`: an empty string under normal circumstances, an error text will be returned under abnormal conditions * `data`: may be `{}`, `[]` or `NULL`, depending on the interface ### Authentication View API token in Settings - About, request header: `Authorization: Token xxx` ## Notebooks ### List notebooks * `/api/notebook/lsNotebooks` * No parameters * Return value ```json { "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 } ] } } ``` ### Open a notebook * `/api/notebook/openNotebook` * Parameters ```json { "notebook": "20210831090520-7dvbdv0" } ``` * `notebook`: Notebook ID * Return value ```json { "code": 0, "msg": "", "data": null } ``` ### Close a notebook * `/api/notebook/closeNotebook` * Parameters ```json { "notebook": "20210831090520-7dvbdv0" } ``` * `notebook`: Notebook ID * Return value ```json { "code": 0, "msg": "", "data": null } ``` ### Rename a notebook * `/api/notebook/renameNotebook` * Parameters ```json { "notebook": "20210831090520-7dvbdv0", "name": "New name for notebook" } ``` * `notebook`: Notebook ID * Return value ```json { "code": 0, "msg": "", "data": null } ``` ### Create a notebook * `/api/notebook/createNotebook` * Parameters ```json { "name": "Notebook name" } ``` * Return value ```json { "code": 0, "msg": "", "data": { "notebook": { "id": "20220126215949-r1wvoch", "name": "Notebook name", "icon": "", "sort": 0, "closed": false } } } ``` ### Remove a notebook * `/api/notebook/removeNotebook` * Parameters ```json { "notebook": "20210831090520-7dvbdv0" } ``` * `notebook`: Notebook ID * Return value ```json { "code": 0, "msg": "", "data": null } ``` ### Get notebook configuration * `/api/notebook/getNotebookConf` * Parameters ```json { "notebook": "20210817205410-2kvfpfn" } ``` * `notebook`: Notebook ID * Return value ```json { "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" } } ``` ### Save notebook configuration * `/api/notebook/setNotebookConf` * Parameters ```json { "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 ```json { "code": 0, "msg": "", "data": { "name": "Test Notebook", "closed": false, "refCreateSavePath": "", "createDocNameTemplate": "", "dailyNoteSavePath": "/daily note/{{now | date \"2006/01\"}}/{{now | date \"2006-01-02\"}}", "dailyNoteTemplatePath": "" } } ``` ## Documents ### Create a document with Markdown * `/api/filetree/createDocWithMd` * Parameters ```json { "notebook": "20210817205410-2kvfpfn", "path": "/foo/bar", "markdown": "" } ``` * `notebook`: Notebook ID * `path`: 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 ```json { "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, but a new document ending with a random number will be created ### Rename a document * `/api/filetree/renameDoc` * Parameters ```json { "notebook": "20210831090520-7dvbdv0", "path": "/20210902210113-0avi12f.sy", "title": "Document new title" } ``` * `notebook`: Notebook ID * `path`: Document path * Return value ```json { "code": 0, "msg": "", "data": null } ``` ### Remove a document * `/api/filetree/removeDoc` * Parameters ```json { "notebook": "20210831090520-7dvbdv0", "path": "/20210902210113-0avi12f.sy" } ``` * `notebook`: Notebook ID * `path`: Document path * Return value ```json { "code": 0, "msg": "", "data": null } ``` ### Move a document * `/api/filetree/moveDoc` * Parameters ```json { "fromNotebook": "20210831090520-7dvbdv0", "fromPath": "/20210917220056-yxtyl7i.sy", "toNotebook": "20210817205410-2kvfpfn", "toPath": "/" } ``` * `fromNotebook`: Source notebook ID * `fromPath`: Source path * `toNotebook`: Target notebook ID * `toPath`: Target path * Return value ```json { "code": 0, "msg": "", "data": null } ``` ### Get human-readable path based on path * `/api/filetree/getHPathByPath` * Parameters ```json { "notebook": "20210831090520-7dvbdv0", "path": "/20210917220500-sz588nq/20210917220056-yxtyl7i.sy" } ``` * `notebook`: Notebook ID * `path`: Document path * Return value ```json { "code": 0, "msg": "", "data": "/foo/bar" } ``` ## Assets ### Upload assets * `/api/asset/upload` * The parameter is an HTTP Multipart form * `assetsDirPath`: The folder path where the assets are stored. The arguments have the following three cases 1. `"/assets/"`: Workspace/data/assets folder 2. `"/Test Notebook/assets/"`: Assets folder under `Test Notebook` 3. `"/Test Notebook/foo/assets/"`: Assets folder under foo folder under `Test notebook` It is recommended to use the first one, which is stored in the workspace assets folder uniformly. * `file[]`: Uploaded file list * Return value ```json { "code": 0, "msg": "", "data": { "errFiles": [""], "succMap": { "foo.png": "assets/foo-20210719092549-9j5y79r.png" } } } ``` * `errFiles`: List of filenames with errors in upload processing * `succMap`: 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 ## Blocks ### Insert blocks * `/api/block/insertBlock` * Parameters ```json { "dataType": "markdown", "data": "foo**bar**{: style=\"color: var(--b3-font-color8);\"}baz", "previousID": "20211229114650-vrek5x6" } ``` * `dataType`: The data type to be inserted, the value can be `markdown` or `dom` * `data`: Data to be inserted * `previousID`: The ID of the previous block, used to anchor the insertion position * Return value ```json { "code": 0, "msg": "", "data": [ { "doOperations": [ { "action": "insert", "data": "
foobarbaz
", "id": "20211230115020-g02dfx0", "parentID": "", "previousID": "20211229114650-vrek5x6", "retData": null } ], "undoOperations": null } ] } ``` * `action.data`: DOM generated by the newly inserted block * `action.id`: ID of the newly inserted block ### Prepend blocks * `/api/block/prependBlock` * Parameters ```json { "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 be `markdown` or `dom` * `data`: Data to be inserted * `parentID`: The ID of the parent block, used to anchor the insertion position * Return value ```json { "code": 0, "msg": "", "data": [ { "doOperations": [ { "action": "insert", "data": "
foobarbaz
", "id": "20220108003710-hm0x9sc", "parentID": "20220107173950-7f9m1nb", "previousID": "", "retData": null } ], "undoOperations": null } ] } ``` * `action.data`: DOM generated by the newly inserted block * `action.id`: ID of the newly inserted block ### Append blocks * `/api/block/appendBlock` * Parameters ```json { "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 be `markdown` or `dom` * `data`: Data to be inserted * `parentID`: The ID of the parent block, used to anchor the insertion position * Return value ```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 generated by the newly inserted block * `action.id`: ID of the newly inserted block ### Update a block * `/api/block/updateBlock` * Parameters ```json { "dataType": "markdown", "data": "foobarbaz", "id": "20211230161520-querkps" } ``` * `dataType`: The data type to be updated, the value can be `markdown` or `dom` * `data`: Data to be updated * `id`: ID of the block to be updated * Return value ```json { "code": 0, "msg": "", "data": [ { "doOperations": [ { "action": "update", "data": "
foobarbaz
", "id": "20211230161520-querkps", "parentID": "", "previousID": "", "retData": null } ], "undoOperations": null } ] } ``` * `action.data`: DOM generated by the updated block ### Delete a block * `/api/block/deleteBlock` * Parameters ```json { "id": "20211230161520-querkps" } ``` * `id`: ID of the block to be deleted * Return value ```json { "code": 0, "msg": "", "data": [ { "doOperations": [ { "action": "delete", "data": null, "id": "20211230162439-vtm09qo", "parentID": "", "previousID": "", "retData": null } ], "undoOperations": null } ] } ``` ## Attributes ### Set block properties * `/api/attr/setBlockAttrs` * Parameters ```json { "id": "20210912214605-uhi5gco", "attrs": { "custom-attr1": "line1\nline2" } } ``` * `id`: Block ID * `attrs`: Block attributes, custom attributes must be prefixed with `custom-` * Return value ```json { "code": 0, "msg": "", "data": null } ``` ### Get block attributes * `/api/attr/getBlockAttrs` * Parameters ```json { "id": "20210912214605-uhi5gco" } ``` * `id`: Block ID * Return value ```json { "code": 0, "msg": "", "data": { "custom-attr1": "line1\nline2", "id": "20210912214605-uhi5gco", "title": "PDF Annotation Demo", "type": "doc", "updated": "20210916120715" } } ``` ## SQL ### Execute SQL query * `/api/query/sql` * Parameters ```json { "stmt": "SELECT * FROM blocks WHERE content LIKE'%content%' LIMIT 7" } ``` * `stmt`: SQL statement * Return value ```json { "code": 0, "msg": "", "data": [ { "col": "val" } ] } ``` ## Templates ### Render a template /template/render ## Export ### Export Markdown * `/api/export/exportMdContent` * Parameters ```json { "id": "" } ``` * `id`: ID of the doc block to export * Return value ```json { "code": 0, "msg": "", "data": { "hPath": "/Please Start Here", "content": "## 🍫 Content Block\n\nIn SiYuan, the only important core concept is..." } } ``` * `hPath`: human-readable path * `content`: Markdown content ## System ### Get boot progress * `/api/system/bootProgress` * No parameters * Return value ```json { "code": 0, "msg": "", "data": { "details": "Finishing boot...", "progress": 100 } } ``` ### Get system version * `/api/system/version` * No parameters * Return value ```json { "code": 0, "msg": "", "data": "1.3.5" } ``` ### Get the current time of the system * `/api/system/currentTime` * No parameters * Return value ```json { "code": 0, "msg": "", "data": 1631850968131 } ``` * `data`: Precision in milliseconds ## Webhook TBD https://ld246.com/article/1627956688432