Drives the SiYuan kernel HTTP API via curl to search, read, create, update, and delete blocks and documents, run SQL, and export Markdown. Use when managing a self-hosted SiYuan (思源笔记) knowledge base. Not for Obsidian vault notes, Apple Notes MCP search, or Notion.
Drives the SiYuan kernel HTTP API via curl to search, read, create, update, and delete blocks and documents, run SQL, and export Markdown. Use when managing a self-hosted SiYuan (思源笔记) knowledge base. Not for Obsidian vault notes, Apple Notes MCP search, or Notion.
[{"name":"SIYUAN_TOKEN","prompt":"SiYuan API token","help":"Settings > About in SiYuan desktop app"},{"name":"SIYUAN_URL","prompt":"SiYuan instance URL (default http://127.0.0.1:6806)","required_for":"remote instances"}]
SiYuan Note API
Use the SiYuan kernel API via curl to search, read, create, update, and delete blocks and documents in a self-hosted knowledge base. No extra tools needed — just curl and an API token.
When to Use
User asks to search, read, create, update, or delete content in a SiYuan knowledge base.
User mentions "SiYuan", "思源笔记", or references a self-hosted PKM with block-level IDs.
User wants to run SQL queries against their notes database or export documents as Markdown.
User needs to manage notebooks, documents, blocks, or block attributes programmatically.
Prerequisites
Install and run SiYuan (desktop app or Docker container).
Get your API token: Settings > About > API token in the SiYuan desktop app.
Store credentials in ${HERMES_HOME:-~/.hermes}/.env:
SIYUAN_URL defaults to http://127.0.0.1:6806 if not set.
Ensure curl and jq are available on PATH.
Windows (PowerShell) note: In PowerShell, use $env:SIYUAN_TOKEN and $env:SIYUAN_URL instead of $SIYUAN_TOKEN. For multi-line JSON bodies, prefer writing the JSON to a temp file and using -d "@file.json" to avoid quoting issues, or use single-quoted here-strings.
Procedure
API Basics
All SiYuan API calls are POST with a JSON body — even read-only operations. Never use GET.
code: 0 means success. Any other value is an error — check msg for details. Always verify code == 0 before processing data.
ID format: SiYuan IDs look like 20210808180117-6v0mkxr (14-digit timestamp + 7 alphanumeric chars). Reject any ID that does not match the pattern YYYYMMDDHHmmss-xxxxxxx.
To delete a whole document: use /api/filetree/removeDocByID with {"id": "DOC_ID"}.
To delete a notebook: use /api/notebook/removeNotebook with {"notebook": "NOTEBOOK_ID"}.
All endpoints are POST — even read-only operations like search and SQL. Do not use GET.
SQL safety: only use SELECT queries. INSERT/UPDATE/DELETE/DROP are dangerous and should never be sent.
ID validation: IDs match the pattern YYYYMMDDHHmmss-xxxxxxx. Reject anything else before making API calls.
Error responses: always check code != 0 in responses before processing data. The msg field contains the error message.
Large documents: block content and export results can be very large. Use LIMIT in SQL and pipe through jq to extract only what you need.
Notebook IDs: when working with a specific notebook, get its ID first via lsNotebooks — do not assume the notebook name is the ID.
Custom attributes: must be prefixed with custom-. Attributes without this prefix may be ignored or overwritten by SiYuan internals.
PowerShell quoting: nested single quotes in SQL JSON bodies are painful in PowerShell. Write the JSON to a temp file and use curl -d "@body.json" to avoid quoting hell.
Closed notebooks: lsNotebooks returns both open and closed notebooks. Filter on closed if you only want accessible notebooks.
Expected: 0 followed by the block's Kramdown content.
Alternative: MCP Server
If you prefer a native integration instead of curl, install the SiYuan MCP server:
# In ~/.hermes/config.yaml under mcp_servers:mcp_servers:siyuan:command:npxargs: ["-y", "@porkll/siyuan-mcp"]
env:SIYUAN_TOKEN:"YOUR_TOKEN"SIYUAN_URL:"http://127.0.0.1:6806"
Related Skills
obsidian — local Markdown-based PKM with file-system access.
notion — cloud-based workspace with database and page APIs.
