思源笔记

通过思源笔记 API 搜索、阅读、创建和管理块和文档

思源笔记（SiYuan）API

通过 curl 使用 SiYuan 内核 API，在自托管知识库中搜索、阅读、创建、更新和删除块及文档。无需额外工具——只需 curl 和 API 令牌。

前置条件

• 安装并运行 SiYuan（桌面版或 Docker）
• 获取 API 令牌：设置 → 关于 → API 令牌
• 保存在 ~/.hermes/.env 中：

   SIYUAN_TOKEN=your_token_here
   SIYUAN_URL=http://127.0.0.1:6806

如果未设置 SIYUAN_URL，默认为 http://127.0.0.1:6806。

API 基础

所有 SiYuan API 调用均为 POST + JSON body。每个请求遵循以下模式：

curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/..." \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"param": "value"}'

响应为 JSON，结构如下：

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

code: 0 表示成功。其他值为错误——查看 msg 获取详情。

ID 格式：SiYuan ID 形如 20210808180117-6v0mkxr（14 位时间戳 + 7 位字母数字）。

快速参考

操作	端点
全文搜索	/api/search/fullTextSearchBlock
SQL 查询	/api/query/sql
读取块	/api/block/getBlockKramdown
读取子块	/api/block/getChildBlocks
获取路径	/api/filetree/getHPathByID
获取属性	/api/attr/getBlockAttrs
列出笔记本	/api/notebook/lsNotebooks
列出文档	/api/filetree/listDocsByPath
创建笔记本	/api/notebook/createNotebook
创建文档	/api/filetree/createDocWithMd
追加块	/api/block/appendBlock
更新块	/api/block/updateBlock
重命名文档	/api/filetree/renameDocByID
设置属性	/api/attr/setBlockAttrs
删除块	/api/block/deleteBlock
删除文档	/api/filetree/removeDocByID
导出为 Markdown	/api/export/exportMdContent

常用操作

搜索（全文）

curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/search/fullTextSearchBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "meeting notes", "page": 0}' | jq '.data.blocks[:5]'

搜索（SQL）

直接查询块数据库。仅 SELECT 语句安全。

curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/query/sql" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stmt": "SELECT id, content, type, box FROM blocks WHERE content LIKE '\''%\''keyword'\''%'\'' AND type='\''p'\'' LIMIT 20"}' | jq '.data'

读取块

# 获取块的 Kramdown（带格式的 Markdown）
curl -s -X POST "${SIYUAN_URL}/api/block/getBlockKramdown" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data.kramdown'

读取子块

curl -s -X POST "${SIYUAN_URL}/api/block/getChildBlocks" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data.blocks[].id'

获取文档路径

curl -s -X POST "${SIYUAN_URL}/api/filetree/getHPathByID" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
# 输出："/我的笔记/工作/会议记录"

列出笔记本

curl -s -X POST "${SIYUAN_URL}/api/notebook/lsNotebooks" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '.data.notebooks'

创建笔记本

curl -s -X POST "${SIYUAN_URL}/api/notebook/createNotebook" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "新笔记本"}' | jq '.data'

创建文档

curl -s -X POST "${SIYUAN_URL}/api/filetree/createDocWithMd" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notebook": "20210808180117-6v0mkxr", "path": "/新文档.md", "markdown": "# 标题\n\n内容"}' | jq '.data'

追加块

curl -s -X POST "${SIYUAN_URL}/api/block/appendBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parentID": "20210808180117-6v0mkxr", "data": "- 新列表项"}' | jq '.data'

更新块

curl -s -X POST "${SIYUAN_URL}/api/block/updateBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-xyzabc", "data": "更新的内容"}' | jq '.data'

删除块

curl -s -X POST "${SIYUAN_URL}/api/block/deleteBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-xyzabc"}' | jq '.'

导出为 Markdown

curl -s -X POST "${SIYUAN_URL}/api/export/exportMdContent" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data.content'

块类型

类型	说明
p	段落（Paragraph）
h	标题（Heding）
q	引用块（Quote Block）
lb	列表块（List Block）
li	列表项（List Item）
code	代码块
tb	表格块
math	数学公式
doc	文档（顶级块）

注意事项

• SiYuan API 仅处理块，不直接处理文档——文档是顶级块
• 所有 ID 都是块级别 ID，没有独立文档 ID
• 使用 /api/filetree/getHPathByID 获取文档的层级路径
• 删除文档 = 删除其顶级块 ID
• 块内容使用 Kramdown 格式（带额外语义的 Markdown）
• 创建块后用 getBlockKramdown 读取以验证格式