[中文](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": "
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 attributes * `/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 /api/template/render ## File ### Get file * `/api/file/getFile` * Parameters ``json { "path": "/data/20210808180117-6v0mkxr/20200923234011-ieuun1p.sy" } `` * `path`: the file path under the workspace path * Return value File content ### Put file * `/api/file/putFile` * The parameter is an HTTP Multipart form * `path`: the file path under the workspace path * `isDir`: whether to create a folder, when `true` only create a folder, ignore `file` * `modTime`: last access and modification time, Unix time * `file`: the uploaded file * return value ```json { "code": 0, "msg": "", "data": null } ``` ## 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