Synology DSM Skill
Interact with a Synology NAS through the DSM Web API using curl.
Prerequisites
The user must have these environment variables set (or provide them inline):
- -
SYNOLOGY_HOST — NAS hostname or IP (e.g., 192.168.1.100) - INLINECODE3 — DSM port (
5000 for HTTP, 5001 for HTTPS) - INLINECODE6 — DSM username
- INLINECODE7 — DSM password
Base URL: INLINECODE8
Security: Always prefer HTTPS (port 5001). Never hardcode credentials in commands shown to the user — use $SYNOLOGY_PASS references. If the user hasn't set env vars, ask them to provide connection details.
Step 1: Authentication
Every session starts with login. Use format=sid to get a session ID.
Login
CODEBLOCK0
Response:
CODEBLOCK1
Save the sid for all subsequent requests: INLINECODE12
Logout
CODEBLOCK2
2FA Handling
If login returns error code 406, the account has 2FA enabled. Ask the user for their OTP code, then include &otp_code=<CODE> in the login request.
Session Notes
- - Sessions timeout after ~15 minutes of inactivity
- If you get error code
106 (session timeout), re-authenticate - Always logout when done to clean up sessions
Step 2: API Discovery (Optional)
Query all available APIs on the NAS:
CODEBLOCK3
This returns every API name, path, and supported version range. Useful for checking what packages are installed.
Step 3: FileStation — File Management
All FileStation calls use _sid=$SID for authentication.
List shared folders (root)
CODEBLOCK4
List files in a folder
CODEBLOCK5
Parameters: folder_path (required), offset, limit, sort_by (name|size|mtime), sort_direction (asc|desc), additional (size,time,perm,type)
Create folder
CODEBLOCK6
Rename file or folder
CODEBLOCK7
Delete file or folder
CODEBLOCK8
For large deletions, use method=start to get a task ID, then poll with method=status&taskid=<id>.
Upload file
CODEBLOCK9
Download file
CODEBLOCK10
Search files
CODEBLOCK11
Get file/folder info
CODEBLOCK12
For full FileStation API reference, see references/filestation-api.md.
Step 4: DownloadStation — Download Management
Get DownloadStation info
CODEBLOCK13
List all download tasks
CODEBLOCK14
The additional=transfer parameter includes download/upload speed and progress.
Add download task (URL)
CODEBLOCK15
Add download task (torrent file)
CODEBLOCK16
Pause / Resume / Delete tasks
CODEBLOCK17
Multiple task IDs can be comma-separated: INLINECODE26
For full DownloadStation API reference, see references/downloadstation-api.md.
Step 5: System Info
Get DSM system information
CODEBLOCK18
Returns: model, RAM, serial, DSM version, uptime, temperature.
Get storage/volume info
CODEBLOCK19
Get network info
CODEBLOCK20
Error Handling
All API responses follow: INLINECODE27
Common error codes
| Code | Meaning | Action |
|---|
| 100 | Unknown error | Retry once |
| 101 |
Bad request | Check parameters |
| 102 | No such API | Package not installed |
| 103 | No such method | Check API version |
| 104 | Version not supported | Use lower version |
| 105 | No permission | Check user privileges |
| 106 | Session timeout | Re-authenticate |
| 107 | Session interrupted | Re-authenticate |
Auth-specific error codes
| Code | Meaning |
|---|
| 400 | Incorrect password |
| 401 |
Account disabled |
| 402 | Permission denied |
| 406 | 2FA code required |
For full error code reference, see references/error-codes.md.
Workflow Example
A typical session:
- 1. Login and capture SID
- Perform operations (list files, add downloads, etc.)
- Logout when done
Always check "success": true in responses before proceeding. On error 106/107, re-login automatically.
Synology DSM 技能
通过 curl 使用 DSM Web API 与 Synology NAS 交互。
前提条件
用户必须设置以下环境变量（或内联提供）：
- - SYNOLOGYHOST — NAS 主机名或 IP（例如 192.168.1.100）
- SYNOLOGYPORT — DSM 端口（HTTP 使用 5000，HTTPS 使用 5001）
- SYNOLOGYUSER — DSM 用户名
- SYNOLOGYPASS — DSM 密码
基础 URL：http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi
安全：始终优先使用 HTTPS（端口 5001）。切勿在向用户展示的命令中硬编码凭据——应使用 $SYNOLOGY_PASS 引用。如果用户未设置环境变量，请要求他们提供连接详情。
步骤 1：身份验证
每个会话都从登录开始。使用 format=sid 获取会话 ID。
登录
bash
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.API.Auth&version=6&method=login\
&account=$SYNOLOGYUSER&passwd=$SYNOLOGYPASS\
&session=FileStation&format=sid | jq .
响应：
json
{data: {sid: YOURSESSIONID}, success: true}
保存 sid 用于所有后续请求：SID=<响应中的值>
登出
bash
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.API.Auth&version=6&method=logout\
&session=FileStation&_sid=$SID
双因素认证处理
如果登录返回错误代码 406，则表示账户已启用双因素认证。请询问用户其 OTP 验证码，然后在登录请求中包含 &otp_code=。
会话说明
- - 会话在约 15 分钟无活动后超时
- 如果收到错误代码 106（会话超时），请重新进行身份验证
- 操作完成后务必登出以清理会话
步骤 2：API 发现（可选）
查询 NAS 上所有可用的 API：
bash
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/query.cgi?\
api=SYNO.API.Info&version=1&method=query | jq .
这将返回每个 API 的名称、路径和支持的版本范围。可用于检查已安装的软件包。
步骤 3：FileStation — 文件管理
所有 FileStation 调用均使用 _sid=$SID 进行身份验证。
列出共享文件夹（根目录）
bash
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.FileStation.List&version=2&method=listshare&sid=$SID | jq .
列出文件夹中的文件
bash
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.FileStation.List&version=2&method=list\
&folderpath=/volume1/homes&additional=size,time&sid=$SID | jq .
参数：folderpath（必填）、offset、limit、sortby（name|size|mtime）、sort_direction（asc|desc）、additional（size,time,perm,type）
创建文件夹
bash
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.FileStation.CreateFolder&version=2&method=create\
&folderpath=/volume1/homes&name=newfolder&_sid=$SID | jq .
重命名文件或文件夹
bash
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.FileStation.Rename&version=2&method=rename\
&path=/volume1/homes/oldname&name=newname&_sid=$SID | jq .
删除文件或文件夹
bash
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.FileStation.Delete&version=2&method=delete\
&path=/volume1/homes/unwantedfile&sid=$SID | jq .
对于大量删除，使用 method=start 获取任务 ID，然后使用 method=status&taskid= 轮询。
上传文件
bash
curl -s -X POST \
-F api=SYNO.FileStation.Upload \
-F version=2 \
-F method=upload \
-F path=/volume1/homes \
-F overwrite=true \
-F file=@/local/path/to/file.txt \
-F _sid=$SID \
http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi
下载文件
bash
curl -s -o output_file.txt \
http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.FileStation.Download&version=2&method=download\
&path=/volume1/homes/file.txt&mode=download&_sid=$SID
搜索文件
bash
开始搜索
curl -s http://$SYNOLOGY
HOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.FileStation.Search&version=2&method=start\
&folder
path=/volume1&pattern=*.pdf&sid=$SID | jq .
返回 taskid
获取结果
curl -s http://$SYNOLOGY
HOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.FileStation.Search&version=2&method=list\
&taskid=
ID>&sid=$SID | jq .
获取文件/文件夹信息
bash
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.FileStation.List&version=2&method=getinfo\
&path=/volume1/homes/file.txt&additional=size,time&_sid=$SID | jq .
有关完整的 FileStation API 参考，请参阅 references/filestation-api.md。
步骤 4：DownloadStation — 下载管理
获取 DownloadStation 信息
bash
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.DownloadStation.Info&version=1&method=getinfo&_sid=$SID | jq .
列出所有下载任务
bash
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.DownloadStation.Task&version=1&method=list\
&additional=transfer&_sid=$SID | jq .
additional=transfer 参数包含下载/上传速度和进度。
添加下载任务（URL）
bash
curl -s -X POST \
-d api=SYNO.DownloadStation.Task&version=1&method=create\
&uri=https://example.com/file.zip&_sid=$SID \
http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi
添加下载任务（种子文件）
bash
curl -s -X POST \
-F api=SYNO.DownloadStation.Task \
-F version=1 \
-F method=create \
-F file=@/local/path/to/file.torrent \
-F _sid=$SID \
http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi
暂停/恢复/删除任务
bash
暂停
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.DownloadStation.Task&version=1&method=pause\
&id=ID>&sid=$SID
恢复
curl -s http://$SYNOLOGYHOST:$SYNOLOGYPORT/webapi/entry.cgi?\
api=SYNO.DownloadStation.Task&version=1&method=resume\
&id=ID>&sid=$SID
删除（force_complete=false 保留已下载的文件）
curl -
