AI TOOLS RADAR
All skills / NOUSRESEARCH
nousresearch/hermes-agent

siyuan

Query and edit a SiYuan knowledge base via its API.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/nousresearch/hermes-agent --skill siyuan

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

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.

Prerequisites

  1. Install and run SiYuan (desktop or Docker)
  2. Get your API token: Settings > About > API token
  3. Store it in ${HERMES_HOME:-~/.hermes}/.env:
   SIYUAN_TOKEN=your_token_here
   SIYUAN_URL=http://127.0.0.1:6806

SIYUAN_URL defaults to http://127.0.0.1:6806 if not set.

API Basics

All SiYuan API calls are POST with JSON body. Every request follows this pattern:

bash
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"}'

Responses are JSON with this structure:

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

code: 0 means success. Any other value is an error -- check msg for details.

ID format: SiYuan IDs look like 20210808180117-6v0mkxr (14-digit timestamp + 7 alphanumeric chars).

Quick Reference

OperationEndpoint
Full-text search/api/search/fullTextSearchBlock
SQL query/api/query/sql
Read block/api/block/getBlockKramdown
Read children/api/block/getChildBlocks
Get path/api/filetree/getHPathByID
Get attributes/api/attr/getBlockAttrs
List notebooks/api/notebook/lsNotebooks
List documents/api/filetree/listDocsByPath
Create notebook/api/notebook/createNotebook
Create document/api/filetree/createDocWithMd
Append block/api/block/appendBlock
Update block/api/block/updateBlock
Rename document/api/filetree/renameDocByID
Set attributes/api/attr/setBlockAttrs
Delete block/api/block/deleteBlock
Delete document/api/filetree/removeDocByID
Export as Markdown/api/export/exportMdContent

Common Operations

Search (Full-Text)

bash
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]'

Search (SQL)

Query the blocks database directly. Only SELECT statements are safe.

bash
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'

Useful columns: id, parent_id, root_id, box (notebook ID), path, content, type, subtype, created, updated.

Read Block Content

Returns block content in Kramdown (Markdown-like) format.

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getBlockKramdown" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data.kramdown'

Read Child Blocks

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

Get Human-Readable Path

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/getHPathByID" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'

Get Block Attributes

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/getBlockAttrs" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'

List Notebooks

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/lsNotebooks" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '.data.notebooks[] | {id, name, closed}'

List Documents in a Notebook

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/listDocsByPath" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notebook": "NOTEBOOK_ID", "path": "/"}' | jq '.data.files[] | {id, name}'

Create a Document

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/createDocWithMd" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notebook": "NOTEBOOK_ID",
    "path": "/Meeting Notes/2026-03-22",
    "markdown": "# Meeting Notes\n\n- Discussed project timeline\n- Assigned tasks"
  }' | jq '.data'

Create a Notebook

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/createNotebook" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My New Notebook"}' | jq '.data.notebook.id'

Append Block to Document

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/appendBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parentID": "DOCUMENT_OR_BLOCK_ID",
    "data": "New paragraph added at the end.",
    "dataType": "markdown"
  }' | jq '.data'

Also available: /api/block/prependBlock (same params, inserts at the beginning) and /api/block/insertBlock (uses previousID instead of parentID to insert after a specific block).

Update Block Content

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/updateBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "BLOCK_ID",
    "data": "Updated content here.",
    "dataType": "markdown"
  }' | jq '.data'

Rename a Document

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/renameDocByID" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "DOCUMENT_ID", "title": "New Title"}'

Set Block Attributes

Custom attributes must be prefixed with custom-:

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/setBlockAttrs" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "BLOCK_ID",
    "attrs": {
      "custom-status": "reviewed",
      "custom-priority": "high"
    }
  }'

Delete a Block

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/deleteBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "BLOCK_ID"}'

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

Export Document as Markdown

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/export/exportMdContent" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "DOCUMENT_ID"}' | jq -r '.data.content'

Block Types

Common type values in SQL queries:

TypeDescription
dDocument (root block)
pParagraph
hHeading
lList
iList item
cCode block
mMath block
tTable
bBlockquote
sSuper block
htmlHTML block

Pitfalls

  • All endpoints are POST -- even read-only operations. 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.
  • Error responses: always check code != 0 in responses before processing data.
  • 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.

Alternative: MCP Server

If you prefer a native integration instead of curl, install the SiYuan MCP server:

yaml
# In ~/.hermes/config.yaml under mcp_servers:
mcp_servers:
  siyuan:
    command: npx
    args: ["-y", "@porkll/siyuan-mcp"]
    env:
      SIYUAN_TOKEN: "your_token"
      SIYUAN_URL: "http://127.0.0.1:6806"

Related by task

affaan-m
Community

knowledge-ops

Knowledge base management, ingestion, sync, and retrieval across multiple storage layers (local files, MCP memory, vector stores, Git repos). Use when the user wants to save, organize, sync, deduplicate, or search across their knowledge systems.

installs
3
GitHub stars
286.1K
Updated
Oct 20
MIT1 Files
View skill details →

Why explore this: Documents

affaan-m
Community

docs-governance

Route broad documentation-governance requests to existing ECC skills and run an opt-in, read-only audit of mapped documentation roles, links, ADR indexes, and evidence references. Use when a user asks for documentation governance, project-knowledge organization, documentation integrity, or a deterministic docs audit without naming a narrower skill.

installs
3
GitHub stars
286.1K
Updated
Oct 20
MIT4 Files
View skill details →

Why explore this: Documents

affaan-m
Community

google-workspace-ops

Operate across Google Drive, Docs, Sheets, and Slides as one workflow surface for plans, trackers, decks, and shared documents. Use when the user needs to find, summarize, edit, migrate, or clean up Google Workspace assets without dropping to raw tool calls.

installs
3
GitHub stars
286.1K
Updated
Oct 20
MIT1 Files
View skill details →

Why explore this: Documents

from this repository

More skills

All skills
nousresearch
Community

pixel-art

Pixel art w/ era palettes (NES, Game Boy, PICO-8).

installs
1
GitHub stars
257.1K
Updated
Oct 26
MIT7 Files
View skill details →
nousresearch
Community

inspecting-hermes-desktop-dom

Read the live Hermes desktop DOM/CSS over CDP.

installs
3
GitHub stars
255.9K
Updated
Oct 22
MIT1 Files
View skill details →
nousresearch
Community

github

GitHub via gh CLI: PRs, issues, reviews, repos, auth.

installs
2
GitHub stars
255.9K
Updated
Oct 22
MIT17 Files
View skill details →
nousresearch
Community

hermes-agent

Use, configure, theme, extend, and orchestrate Hermes Agent.

installs
2
GitHub stars
255.9K
Updated
Oct 22
MIT22 Files
View skill details →