SiYuan Note API

SiYuan のカーネル API を curl 経由で使用して、セルフホスト型ナレッジベース内のブロックとドキュメントを検索、読み込み、作成、更新、削除できます。追加ツールは不要です。curl と API トークンがあれば十分です。

前提条件

1. SiYuan（デスクトップまたは Docker）をインストールして実行する
2. API トークンを取得する：Settings > About > API token
3. ~/.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 呼び出しは JSON ボディを含む POST です。すべてのリクエストは以下のパターンに従います：

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'

便利なカラム：id、parent_id、root_id、box（ノートブック ID）、path、content、type、subtype、created、updated。

ブロックコンテンツを読み込む

ブロックコンテンツを Kramdown（Markdown ライク）フォーマットで返します。

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'

子ブロックを読み込む

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'

人間が読める形式のパスを取得

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'

ブロック属性を取得

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'

ノートブックを一覧表示

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

ノートブック内のドキュメントを一覧表示

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

ドキュメントを作成

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'

ノートブックを作成

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'

ドキュメントにブロックを追加

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'

他にも利用可能：/api/block/prependBlock（同じパラメータで、最初に挿入）と /api/block/insertBlock（parentID の代わりに previousID を使用して特定のブロックの後に挿入）。

ブロックコンテンツを更新

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'

ドキュメント名を変更

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

ブロック属性を設定

カスタム属性は custom- プレフィックスを付ける必要があります：

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

ブロックを削除

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

ドキュメント全体を削除する場合：/api/filetree/removeDocByID を {"id": "DOC_ID"} で使用します。 ノートブックを削除する場合：/api/notebook/removeNotebook を {"notebook": "NOTEBOOK_ID"} で使用します。

ドキュメントを Markdown としてエクスポート

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'

ブロックタイプ

SQL クエリで使用される一般的な type 値：

タイプ	説明
d	ドキュメント（ルートブロック）
p	段落
h	見出し
l	リスト
i	リストアイテム
c	コードブロック
m	数式ブロック
t	テーブル
b	ブロッククオート
s	スーパーブロック
html	HTML ブロック

よくある落とし穴

• すべてのエンドポイントは POST です。読み取り専用操作であっても GET を使用しないでください。
• SQL の安全性：SELECT クエリのみを使用してください。INSERT/UPDATE/DELETE/DROP は危険であり、送信してはいけません。
• ID 検証：ID は YYYYMMDDHHmmss-xxxxxxx パターンに一致します。それ以外は拒否してください。
• エラーレスポンス：data を処理する前に、レスポンス内で常に code != 0 をチェックしてください。
• 大規模ドキュメント：ブロックコンテンツとエクスポート結果は非常に大きくなる可能性があります。SQL で LIMIT を使用し、jq を通してパイプして必要な部分のみを抽出してください。
• ノートブック ID：特定のノートブックで作業する場合は、最初に lsNotebooks 経由でそのID を取得してください。

代替案：MCP サーバー

curl ではなくネイティブ統合を希望する場合は、SiYuan MCP サーバーをインストールしてください：

# ~/.hermes/config.yaml の 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"