siyuan/API.md at 135696714ecb5bc75a05be87b86add40bf200667

Andreas/siyuan

Fork 0

mirror of https://github.com/siyuan-note/siyuan.git synced 2025-12-16 14:40:12 +01:00

Liang Ding 6723b3a20d

🎨 新增获取块 kramdown 源代码的 API https://github.com/siyuan-note/siyuan/issues/5289

2022-06-27 23:03:31 +08:00

19 KiB

Raw Blame History

中文

Specification
- Parameters and return values
- Authentication
Notebooks
Documents
Assets
- Upload assets
Blocks
Attributes
- Set block attributes
- Get block attributes
SQL
- Execute SQL query
Templates
- Render a template
File
- Get file
- Put file
Export
- Export Markdown
Notification
- Push message
- Push error message
System
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
```
{
  "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

{
  "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

{
  "notebook": "20210831090520-7dvbdv0"
}

notebook: Notebook ID

Return value

{
  "code": 0,
  "msg": "",
  "data": null
}

Close a notebook

/api/notebook/closeNotebook

Parameters

{
  "notebook": "20210831090520-7dvbdv0"
}

notebook: Notebook ID

Return value

{
  "code": 0,
  "msg": "",
  "data": null
}

Rename a notebook

/api/notebook/renameNotebook

Parameters

{
  "notebook": "20210831090520-7dvbdv0",
  "name": "New name for notebook"
}

notebook: Notebook ID

Return value

{
  "code": 0,
  "msg": "",
  "data": null
}

Create a notebook

/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
    }
  }
}

Remove a notebook

/api/notebook/removeNotebook

Parameters

{
  "notebook": "20210831090520-7dvbdv0"
}

notebook: Notebook ID

Return value

{
  "code": 0,
  "msg": "",
  "data": null
}

Get notebook configuration

/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"
  }
}

Save notebook configuration

/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": ""
  }
}

Documents

Create a document with Markdown

/api/filetree/createDocWithMd
Parameters
```
{
  "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
```
{
  "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

{
  "notebook": "20210831090520-7dvbdv0",
  "path": "/20210902210113-0avi12f.sy",
  "title": "Document new title"
}

notebook: Notebook ID
path: Document path

Return value

{
  "code": 0,
  "msg": "",
  "data": null
}

Remove a document

/api/filetree/removeDoc

Parameters

{
  "notebook": "20210831090520-7dvbdv0",
  "path": "/20210902210113-0avi12f.sy"
}

notebook: Notebook ID
path: Document path

Return value

{
  "code": 0,
  "msg": "",
  "data": null
}

Move a document

/api/filetree/moveDoc

Parameters

{
  "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

{
  "code": 0,
  "msg": "",
  "data": null
}

Get human readable path based on path

/api/filetree/getHPathByPath

Parameters

{
  "notebook": "20210831090520-7dvbdv0",
  "path": "/20210917220500-sz588nq/20210917220056-yxtyl7i.sy"
}

notebook: Notebook ID
path: Document path

Return value

{
  "code": 0,
  "msg": "",
  "data": "/foo/bar"
}

Get human readable path based on ID

/api/filetree/getHPathByID
Parameters
```
{
  "id": "20210917220056-yxtyl7i"
}
```
- id：Block ID

Return value

{
  "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
```
{
  "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
```
{
  "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

{
  "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
```
{
  "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

{
  "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
```
{
  "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

{
  "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
```
{
  "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

{
  "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
```
{
  "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
    }
  ]
}

Get a block kramdown

/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\"}"
  }
}

Attributes

Set block attributes

/api/attr/setBlockAttrs

Parameters

{
  "id": "20210912214605-uhi5gco",
  "attrs": {
    "custom-attr1": "line1\nline2"
  }
}

id: Block ID
attrs: Block attributes, custom attributes must be prefixed with custom-

Return value

{
  "code": 0,
  "msg": "",
  "data": null
}

Get block attributes

/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"
  }
}

SQL

Execute SQL query

/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" }
  ]
}

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

{
  "code": 0,
  "msg": "",
  "data": null
}

Export

Export Markdown

/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 path
content: Markdown content

Notification

Push message

/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

Push error message

/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

System

Get boot progress

/api/system/bootProgress
No parameters

Return value

{
  "code": 0,
  "msg": "",
  "data": {
    "details": "Finishing boot...",
    "progress": 100
  }
}

Get system version

/api/system/version
No parameters

Return value

{
  "code": 0,
  "msg": "",
  "data": "1.3.5"
}

Get the current time of the system

/api/system/currentTime
No parameters

Return value

{
  "code": 0,
  "msg": "",
  "data": 1631850968131
}

data: Precision in milliseconds

Webhook

TBD

https://ld246.com/article/1627956688432

19 KiB Raw Blame History Unescape Escape

Specification

Parameters and return values

Authentication

Notebooks

List notebooks

Open a notebook

Close a notebook

Rename a notebook

Create a notebook

Remove a notebook

Get notebook configuration

Save notebook configuration

Documents

Create a document with Markdown

Rename a document

Remove a document

Move a document

Get human readable path based on path

Get human readable path based on ID

Assets

Upload assets

Blocks

Insert blocks

Prepend blocks

Append blocks

Update a block

Delete a block

Get a block kramdown

Attributes

Set block attributes

Get block attributes

SQL

Execute SQL query

Templates

Render a template

File

Get file

Put file

Export

Export Markdown

Notification

Push message

Push error message

System

Get boot progress

Get system version

Get the current time of the system

Webhook

19 KiB

Raw Blame History