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

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 documents

/api/filetree/moveDocs

Parameters

{
  "fromPaths": ["/20210917220056-yxtyl7i.sy"],
  "toNotebook": "20210817205410-2kvfpfn",
  "toPath": "/"
}

fromPaths: Source paths
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
Parameters
```
{
  "id": "20220724223548-j6g0o87",
  "path": "F:\\SiYuan\\data\\templates\\foo.md"
}
```
- id: The ID of the document where the rendering is called
- path: Template file absolute path

Return value

{
  "code": 0,
  "msg": "",
  "data": {
    "content": "<div data-node-id=\"20220729234848-dlgsah7\" data-node-index=\"1\" data-type=\"NodeParagraph\" class=\"p\" updated=\"20220729234840\"><div contenteditable=\"true\" spellcheck=\"false\">foo</div><div class=\"protyle-attr\" contenteditable=\"false\"></div></div>",
    "path": "F:\\SiYuan\\data\\templates\\foo.md"
  }
}

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

Files

API.md

Latest commit

History

API.md

File metadata and controls

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 documents

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