siyuan-api（siyuan API 搜索）

SiYuan Skill

本技能用于调用本地运行的 SiYuan HTTP API，支持笔记本、文档、块、资源、SQL 查询等常见操作。 它只描述调用规范和示例，不包含可执行安装脚本或第三方依赖。

Security Scope

• Only call local SiYuan endpoint (127.0.0.1, localhost, or user-provided local URL).
• Do not send requests to third-party internet endpoints.
• Never hardcode or print SIYUAN_API_TOKEN in logs.
• This skill has read/write authority over your SiYuan notes. Use only in trusted local environments.

Configuration

Configuration can be provided via environment variables in your shell, for example:

export SIYUAN_API_TOKEN=your_token_here
export SIYUAN_API_URL=http://127.0.0.1:6806

• SIYUAN_API_TOKEN (required): from SiYuan Settings > About.
• SIYUAN_API_URL (optional): defaults to http://127.0.0.1:6806.

Typical Use Cases

• Create, rename, and remove notebooks
• Create documents from Markdown
• Insert, append, update, move, and delete blocks
• Upload assets
• Query notes by SQL
• Export documents as Markdown
• Read/write workspace files through SiYuan file APIs

API References

• references/api-zh.md (Chinese)
• references/api.md (English)

Common Examples

List Notebooks

const SIYUAN_API_TOKEN = process.env.SIYUAN_API_TOKEN;
const SIYUAN_API_URL = process.env.SIYUAN_API_URL || 'http://127.0.0.1:6806';

fetch(`${SIYUAN_API_URL}/api/notebook/lsNotebooks`, {
  method: 'POST',
  headers: {
    'Authorization': 'token ' + SIYUAN_API_TOKEN,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
})

Create Document with Markdown

const SIYUAN_API_TOKEN = process.env.SIYUAN_API_TOKEN;
const SIYUAN_API_URL = process.env.SIYUAN_API_URL || 'http://127.0.0.1:6806';

fetch(`${SIYUAN_API_URL}/api/filetree/createDocWithMd`, {
  method: 'POST',
  headers: {
    'Authorization': 'token ' + SIYUAN_API_TOKEN,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    notebook: '笔记本ID',
    path: '/文档路径',
    markdown: '# 文档标题\
\
正文内容...'
  })
})

Append Block

const SIYUAN_API_TOKEN = process.env.SIYUAN_API_TOKEN;
const SIYUAN_API_URL = process.env.SIYUAN_API_URL || 'http://127.0.0.1:6806';

fetch(`${SIYUAN_API_URL}/api/block/appendBlock`, {
  method: 'POST',
  headers: {
    'Authorization': 'token ' + SIYUAN_API_TOKEN,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    parentID: '父块ID',
    dataType: 'markdown',
    data: '追加的内容'
  })
})

SQL Query

const SIYUAN_API_TOKEN = process.env.SIYUAN_API_TOKEN;
const SIYUAN_API_URL = process.env.SIYUAN_API_URL || 'http://127.0.0.1:6806';

fetch(`${SIYUAN_API_URL}/api/query/sql`, {
  method: 'POST',
  headers: {
    'Authorization': 'token ' + SIYUAN_API_TOKEN,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stmt: 'SELECT id, content FROM blocks WHERE content LIKE "%关键词%" LIMIT 10'
  })
})

Notes

• Repeated createDocWithMd on the same path does not overwrite existing documents.
• Custom block attributes must be prefixed with custom-.
• All endpoints use POST and return { code, msg, data }.
• Header format is Authorization: token <your-token> (lowercase token).