[中文](https://github.com/siyuan-note/siyuan/blob/master/API_zh_CN.md) * [Specification](#Specification) * [Parameters and return values](#Parameters-and-return-values) * [Authentication](#Authentication) * [Notebooks](#Notebooks) * [List notebooks](#List-notebooks) * [Open a notebook](#Open-a-notebook) * [Close a notebook](#Close-a-notebook) * [Rename a notebook](#Rename-a-notebook) * [Create a notebook](#Create-a-notebook) * [Remove a notebook](#Remove-a-notebook) * [Get notebook configuration](#Get-notebook-configuration) * [Save notebook configuration](#Save-notebook-configuration) * [Documents](#Documents) * [Create a document with Markdown](#Create-a-document-with-Markdown) * [Rename a document](#Rename-a-document) * [Remove a document](#Remove-a-document) * [Move a document](#Move-a-document) * [Get human-readable path based on path](#Get-human-readable-path-based-on-path) * [Get human-readable path based on ID](#Get-human-readable-path-based-on-ID) * [Assets](#Assets) * [Upload assets](#Upload-assets) * [Blocks](#Blocks) * [Insert blocks](#Insert-blocks) * [Prepend blocks](#Prepend-blocks) * [Append blocks](#Append-blocks) * [Update a block](#Update-a-block) * [Delete a block](#Delete-a-block) * [Attributes](#Attributes) * [Set block attributes](#Set-block-attributes) * [Get block attributes](#Get-block-attributes) * [SQL](#SQL) * [Execute SQL query](#Execute-SQL-query) * [Templates](#Templates) * [Render a template](#Render-a-template) * [File](#File) * [Get File](#Get-file) * [Put File](#Put-file) * [Export](#Export) * [Export Markdown](#Export-Markdown) * [System](#System) * [Get boot progress](#Get-boot-progress) * [Get system version](#Get-system-version) * [Get the current time of the system](#Get-the-current-time-of-the-system) * [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" } ``` ### Get human readable path based on ID * `/api/filetree/getHPathByID` * Parameters ```json { "id": "20210917220056-yxtyl7i" } ``` * `id`:Block ID * 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": "