mirror of
https://github.com/siyuan-note/siyuan.git
synced 2025-02-28 05:32:52 +00:00
834 lines
16 KiB
Markdown
834 lines
16 KiB
Markdown
* [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 <kbd>Settings - About</kbd>, 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": "<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 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": "<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 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": "<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 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": "<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
|
|
|
|
### 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 |