Query and edit a SiYuan knowledge base via its API with curl
Query and edit a self-hosted SiYuan knowledge base through its kernel API using curl, to search, read, create, update, and delete blocks and documents.
Requirements
- Requires a running SiYuan instance (desktop or Docker), the SIYUAN_TOKEN environment variable holding your API token, and curl and jq available. SIYUAN_URL is additionally needed for remote instances.
- No extra tools are needed beyond curl and an API token.
- Install and run SiYuan, as a desktop app or via Docker.
- Get your API token from Settings > About > API token in the SiYuan desktop app.
- SIYUAN_URL defaults to http://127.0.0.1:6806 if not set.
How to use
SIYUAN_URL defaults to http://127.0.0.1:6806 if not set.
Before using the API, complete the prerequisites: install and run SiYuan (desktop or Docker), and get your API token from Settings > About > API token.
Install and run SiYuan, either as a desktop app or via Docker.
Get your API token from Settings > About > API token.
Store the token in your environment variables: set SIYUAN_TOKEN to your token and SIYUAN_URL to your SiYuan instance URL.
SIYUAN_TOKEN=your_token_here
SIYUAN_URL=http://127.0.0.1:6806
All SiYuan API endpoints are reached the same way.
Every API call is a POST request with a JSON body: send it to the endpoint under SIYUAN_URL with an Authorization header containing your token and a Content-Type of application/json.
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"}'
{"code": 0, "msg": "", "data": { ... }}
A response code of 0 means success; any other value is an error, and the msg field tells you what went wrong.
For full-text search, post to the fullTextSearchBlock endpoint with a query string and page number, then filter the returned blocks with jq.
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]'
For SQL search, post a statement to the query/sql endpoint to query the blocks database directly.
Only SELECT statements are safe; never send INSERT, UPDATE, DELETE, or DROP.
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'
To read a block's content, post its ID to getBlockKramdown; the response returns the content in Kramdown (Markdown-like) format.
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'
To list a block's children, post its ID to getChildBlocks.
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'
To get a human-readable path for a block, post its ID to getHPathByID.
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'
To read a block's attributes, post its ID to getBlockAttrs.
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'
To list notebooks, post an empty JSON body to lsNotebooks and extract each notebook's id, name, and closed status.
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}'
To list documents in a notebook, post the notebook ID and a path to listDocsByPath.
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}'
To create a document, post to createDocWithMd with the notebook ID, a path, and Markdown content.
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'
To create a notebook, post its name to createNotebook.
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'
To append a block to a document, post to appendBlock with the parent document or block ID, the new content, and dataType markdown.
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'
To update a block's content, post to updateBlock with the block ID, the new content, and dataType markdown.
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'
To rename a document, post to renameDocByID with the document ID and the new title.
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"}'
To set a block's attributes, post to setBlockAttrs with the block ID and an attrs object.
Custom attributes must be prefixed with custom-, as in custom-status or custom-priority.
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"
}
}'
To delete a block, post its ID to deleteBlock.
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 export a document as Markdown, post its ID to exportMdContent and extract the content field.
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'
All endpoints are POST, even read-only operations; do not use GET.
For SQL queries, use only SELECT; INSERT, UPDATE, DELETE, and DROP are dangerous and should never be sent.
Block IDs match the pattern shown; reject anything else.
Always check the code field in responses before processing the data.
Block content and export results can be very large; use LIMIT in SQL and pipe through jq to extract only what you need.
When working with a specific notebook, get its ID first via lsNotebooks.
Alternative: if you prefer a native integration instead of curl, install the SiYuan MCP server.
Add the @porkll/siyuan-mcp server under mcp_servers in your configuration, with your SIYUAN_TOKEN and SIYUAN_URL set in its environment.
# 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"
Source: nousresearch/hermes-agent and its contributors. License: MIT.
Copyright (c) 2025 Nous Research
Translation and editorial adaptation by ClawCases.
>Resources
>Related Use Cases
Apple Notes CLI
Manage Apple Notes directly from the terminal with the memo CLI: create, view, edit, delete, search, move notes between folders, and export notes to HTML or Markdown.
Automate the macOS UI with the Peekaboo CLI
Use Peekaboo to inspect the macOS UI, act on the intended target, and verify the result. The examples use v4 syntax; check the current documentation and the installed command's help, and for older versions follow that version's help.
Distributed PyTorch training with HuggingFace Accelerate
HuggingFace Accelerate lets you run the same PyTorch training script on CPU, single or multi-GPU, multi-node, TPU, or Apple MPS setups by adding a few lines of code.