siyuan

Search and manage SiYuan blocks and documents via curl-based POST JSON API calls.

Updated Apr 9, 2026
One-click install
npx skills add https://github.com/MarbleSodas/Mavis --skill siyuan-marblesodas
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: siyuan
Source: https://github.com/MarbleSodas/Mavis/tree/main/optional-skills/productivity/siyuan
Command: npx skills add https://github.com/MarbleSodas/Mavis --skill siyuan-marblesodas

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

You need a reliable way to programmatically search and manage your SiYuan knowledge base without manually clicking through the UI.

Core Features & Use Cases

  • Full-text and SQL querying: Find blocks and document content using SiYuan endpoints suitable for search workflows.
  • Block and document CRUD: Read block Kramdown, traverse block trees, create/update/delete blocks, and manage notebooks and documents.
  • Metadata and export support: Fetch attributes, set custom attributes, and export documents as Markdown for downstream processing.

Quick Start

Use the siyuan skill to search for the phrase meeting notes in your SiYuan instance and return the top matching blocks.

Frequently Asked Questions about siyuan

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I search for blocks in my SiYuan knowledge base via API?

You can search for blocks in your SiYuan knowledge base by sending curl-based POST JSON API calls to specific SiYuan REST endpoints, enabling full-text and SQL-backed block retrieval using an Authorization: Token header.

Can I create and update SiYuan documents programmatically without the UI?

Yes, you can perform CRUD operations on SiYuan blocks and documents programmatically by sending POST JSON requests to the API, allowing you to create, update, and delete blocks as well as manage notebooks without manual UI interaction.

Do I need an API token to access SiYuan notes endpoints?

Yes, accessing SiYuan notes endpoints requires the SIYUAN_TOKEN to send Authorization: Token headers, and optionally the SIYUAN_URL if you are targeting a self-hosted environment instead of the default instance.

What's the best way to export SiYuan documents as Markdown for downstream processing?

The best way to export SiYuan documents as Markdown is by using the API's metadata and export support endpoints, which fetch attributes and convert document content into Markdown format suitable for downstream programmatic processing.

How does block tree traversal work when reading SiYuan notes via API?

Block tree traversal works by querying the SiYuan API to read block Kramdown and navigate the hierarchical block structures, allowing you to programmatically fetch nested document content and metadata attributes.

Why does my SiYuan API request fail during block search?

SiYuan API requests fail during block search if the SIYUAN_TOKEN is missing or invalid, preventing proper Authorization: Token header validation, or if the POST JSON payload targets an incorrect REST endpoint for the operation.