Выполняйте запросы и редактируйте базу знаний SiYuan через её API с помощью curl
Выполняйте запросы и редактируйте локально размещённую базу знаний SiYuan через её ядерный API с использованием curl для поиска, чтения, создания, обновления и удаления блоков и документов.
Что понадобится
- Требуется запущенный экземпляр SiYuan (десктопная версия или Docker), переменная окружения SIYUAN_TOKEN с вашим токеном API, а также наличие утилит curl и jq. Для удалённых экземпляров необходимо указать параметр SIYUAN_URL.
- Для работы не требуются дополнительные инструменты, кроме curl и токена API.
- Установите и запустите SiYuan — как десктопное приложение или через Docker.
- Получите свой токен API в меню «Настройки» > «О программе» > «Токен API» в десктопном приложении SiYuan.
- Если параметр SIYUAN_URL не задан, он по умолчанию принимает значение
http://127.0.0.1:6806.
Как применить
Если параметр SIYUAN_URL не задан, он по умолчанию принимает значение http://127.0.0.1:6806.
Перед использованием API выполните необходимые предварительные шаги: установите и запустите SiYuan (десктопная версия или Docker), а также получите свой токен API в меню «Настройки» > «О программе» > «Токен API».
Установите и запустите SiYuan — либо как десктопное приложение, либо через Docker.
Получите свой токен API в меню «Настройки» > «О программе» > «Токен API».
Сохраните токен в переменных окружения: установите SIYUAN_TOKEN равным вашему токену, а SIYUAN_URL — адресом экземпляра SiYuan.
SIYUAN_TOKEN=your_token_here
SIYUAN_URL=http://127.0.0.1:6806
Все конечные точки API SiYuan используют один и тот же способ взаимодействия.
Каждый вызов API представляет собой запрос POST с JSON-телом: отправьте его на соответствующую конечную точку по адресу SIYUAN_URL, добавив заголовок Authorization с вашим токеном и указав Content-Type как 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": { ... }}
Код ответа 0 означает успех; любое другое значение указывает на ошибку, а поле msg содержит информацию о причине сбоя.
Для полнотекстового поиска отправьте запрос на конечную точку fullTextSearchBlock, указав строку запроса и номер страницы, затем отфильтруйте полученные блоки с помощью 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]'
Для SQL-запросов отправьте оператор на конечную точку query/sql, чтобы напрямую запросить базу данных блоков.
Безопасными являются только операторы SELECT; никогда не отправляйте команды INSERT, UPDATE, DELETE или 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'
Чтобы прочитать содержимое блока, отправьте его идентификатор на конечную точку getBlockKramdown; в ответе будет представлено содержимое в формате 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'
Чтобы получить список дочерних блоков, отправьте их родительский идентификатор на конечную точку 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'
Чтобы получить человекочитаемый путь к блоку, отправьте его идентификатор на конечную точку 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'
Чтобы прочитать атрибуты блока, отправьте его идентификатор на конечную точку 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'
Чтобы получить список записных книг, отправьте пустое JSON-тело на конечную точку lsNotebooks и извлеките из результата id, название и статус закрытия каждой книги.
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}'
Чтобы получить список документов в записной книге, отправьте её идентификатор и путь на конечную точку 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}'
Чтобы создать документ, отправьте запрос на конечную точку createDocWithMd, указав идентификатор записной книги, путь и содержимое в формате Markdown.
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'
Чтобы создать записную книгу, отправьте её название на конечную точку 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'
Чтобы добавить блок в документ, отправьте запрос на конечную точку appendBlock, указав идентификатор родительского документа или блока, новое содержимое и тип данных 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'
Чтобы обновить содержимое блока, отправьте запрос на конечную точку updateBlock, указав идентификатор блока, новое содержимое и тип данных 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'
Чтобы переименовать документ, отправьте запрос на конечную точку renameDocByID, указав идентификатор документа и новое название.
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"}'
Чтобы изменить атрибуты блока, отправьте запрос на конечную точку setBlockAttrs, указав идентификатор блока и объект атрибутов.
Пользовательские атрибуты должны начинаться с префикса custom-, например custom-status или 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"
}
}'
Чтобы удалить блок, отправьте его идентификатор на конечную точку 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"}'
Чтобы экспортировать документ в формате Markdown, отправьте его идентификатор на конечную точку exportMdContent и извлеките поле content.
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'
Все конечные точки используют метод POST, даже для операций чтения; не используйте метод GET.
Для SQL-запросов применяйте только оператор SELECT; команды INSERT, UPDATE, DELETE и DROP опасны и никогда не должны отправляться.
Идентификаторы блоков соответствуют указанному шаблону; любые другие значения следует отклонять.
Всегда проверяйте поле code в ответах перед обработкой данных.
Блокируемый контент и результаты экспорта могут быть очень большими; используйте оператор LIMIT в SQL и передайте вывод через jq, чтобы извлечь только необходимое.
При работе с конкретной записной книжкой сначала получите её ID с помощью команды lsNotebooks.
Альтернатива: если вы предпочитаете нативную интеграцию вместо curl, установите сервер SiYuan MCP.
Добавьте сервер @porkll/siyuan-mcp в раздел mcp_servers в своей конфигурации, указав значения переменных окружения SIYUAN_TOKEN и SIYUAN_URL.
# 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"
Источник: nousresearch/hermes-agent и участники проекта. Лицензия: MIT.
Copyright (c) 2025 Nous Research
Перевод и редакционная адаптация: ClawCases.
>Ресурсы
>Похожие юзкейсы
Командная строка Apple Notes
Управляйте заметками Apple непосредственно из терминала с помощью CLI memo: создавайте, просматривайте, редактируйте, удаляйте, искайте заметки, перемещайте их между папками и экспортируйте в формате HTML или Markdown.
Автоматизируйте интерфейс macOS с помощью CLI-инструмента Peekaboo
Используйте Peekaboo для анализа интерфейса macOS, взаимодействия с нужным элементом и проверки результата. Примеры используют синтаксис версии 4; ознакомьтесь с актуальной документацией и справкой установленной команды. Для старых версий следуйте инструкциям соответствующей версии.
Обнаруживайте, управляйте и публикуйте скиллы с помощью ClawHub
Если необходимая функциональность отсутствует, ищите соответствующие скиллы в ClawHub, а затем устанавливайте, проверяйте, обновляйте, удаляйте, публикуйте или синхронизируйте их.