Synology DSM Skill

intent

interact with a synology NAS through the DSM web API using curl. this skill handles authentication via login/logout, file management through FileStation (list, create, rename, delete, upload, download, search), download task management through DownloadStation (add, pause, resume, delete), and system queries (DSM info, storage, network). use this skill when the user needs to manage files on their NAS, track downloads, or check system status. requires network access to the NAS and valid DSM credentials.

inputs

environment variables (set these before running, or ask the user to provide them inline):

• SYNOLOGY_HOST - NAS hostname or IP address, e.g. 192.168.1.100 or nas.local
• SYNOLOGY_PORT - DSM listening port: 5000 for HTTP, 5001 for HTTPS. defaults to 5000 if omitted
• SYNOLOGY_USER - DSM username with file/download permissions
• SYNOLOGY_PASS - DSM password (never hardcode in command output; use $SYNOLOGY_PASS variable references)

external connection:

• HTTP/HTTPS access to http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi (or HTTPS if port 5001). must be reachable from the execution environment. network timeouts typically occur after 30 seconds of inactivity.

optional parameters (for specific operations):

• SID - session ID obtained after successful login. valid for ~15 minutes of inactivity before auto-expiration
• TASK_ID - returned by long-running operations like search or multi-file delete, used to poll status
• OTP_CODE - 6-digit code if 2FA is enabled on the account

security notes:

• prefer HTTPS (port 5001) for production. HTTP (port 5000) transmits credentials in cleartext
• if env vars are not set, ask the user before proceeding. do not assume defaults
• always use $SYNOLOGY_PASS variable references in examples; never show the actual password

procedure

step 1: authenticate and obtain session ID

input: SYNOLOGY_HOST, SYNOLOGY_PORT, SYNOLOGY_USER, SYNOLOGY_PASS

output: SID (session ID string) or error code

run login request:

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.API.Auth&version=6&method=login\
&account=$SYNOLOGY_USER&passwd=$SYNOLOGY_PASS\
&session=FileStation&format=sid" | jq .

expected response on success:

{"data": {"sid": "YOUR_SESSION_ID"}, "success": true}

extract the sid value and store it: SID=<value from response>

common outcomes at this step:

• success: true with sid - login succeeded, proceed to next step
• error code 400 - incorrect password, ask user to verify credentials
• error code 401 - account is disabled on the NAS, contact NAS admin
• error code 402 - user lacks API permission, enable in DSM control panel
• error code 406 - 2FA is enabled, proceed to 2FA handling (see decision points)
• network timeout - NAS unreachable, verify host and port

step 2 (optional): query available APIs

input: SYNOLOGY_HOST, SYNOLOGY_PORT, SID

output: JSON list of all available API endpoints on the NAS

to check which packages/features are installed:

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/query.cgi?\
api=SYNO.API.Info&version=1&method=query" | jq .

this is useful for determining if DownloadStation or other packages are present before attempting operations. skip this step if you know which APIs you need.

step 3: perform file operations via FileStation

input: SYNOLOGY_HOST, SYNOLOGY_PORT, SID, (folder_path, file path, or search pattern as needed)

output: JSON response with file list, info, or confirmation of action

3a: list root shares

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.FileStation.List&version=2&method=list_share&_sid=$SID" | jq .

returns: all shared folders (e.g. /volume1/homes, /volume1/downloads)

3b: list files in a folder

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.FileStation.List&version=2&method=list\
&folder_path=/volume1/homes&additional=size,time&_sid=$SID" | jq .

parameters:

• folder_path (required) - path to list, e.g. /volume1/homes
• offset (optional) - start position, default 0
• limit (optional) - max results, default 100
• sort_by (optional) - name, size, or mtime
• sort_direction (optional) - asc or desc
• additional (optional) - comma-separated: size, time, perm, type

3c: create a folder

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.FileStation.CreateFolder&version=2&method=create\
&folder_path=/volume1/homes&name=new_folder&_sid=$SID" | jq .

3d: rename a file or folder

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.FileStation.Rename&version=2&method=rename\
&path=/volume1/homes/old_name&name=new_name&_sid=$SID" | jq .

3e: delete a file or folder

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.FileStation.Delete&version=2&method=delete\
&path=/volume1/homes/unwanted_file&_sid=$SID" | jq .

for large deletions (multiple files or folders), use method=start first to get a taskid, then poll method=status&taskid=<id> until complete.

3f: upload a file

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://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi"

parameters:

• path (required) - destination folder on NAS
• overwrite (optional) - true or false, default false
• file - local file to upload

3g: download a file

curl -s -o output_file.txt \
  "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.FileStation.Download&version=2&method=download\
&path=/volume1/homes/file.txt&mode=download&_sid=$SID"

output is binary file content, redirected to local filename.

3h: search for files

input: search pattern (wildcard or regex), folder to search

output: task ID (from start), then results (from list)

start search:

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.FileStation.Search&version=2&method=start\
&folder_path=/volume1&pattern=*.pdf&_sid=$SID" | jq .

returns taskid. then retrieve results:

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.FileStation.Search&version=2&method=list\
&taskid=<TASK_ID>&_sid=$SID" | jq .

may need to poll multiple times if search is still in progress (check "finished": true).

3i: get file or folder info

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.FileStation.List&version=2&method=getinfo\
&path=/volume1/homes/file.txt&additional=size,time&_sid=$SID" | jq .

returns: size, modified time, permissions, type, etc.

step 4: manage downloads via DownloadStation

input: SYNOLOGY_HOST, SYNOLOGY_PORT, SID, (download URL or torrent file, task IDs)

output: download list, task info, or task creation confirmation

prerequisite: DownloadStation package must be installed on the NAS. verify with step 2 (API query) if unsure.

4a: get DownloadStation info

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.DownloadStation.Info&version=1&method=getinfo&_sid=$SID" | jq .

returns: enabled status, destination folder, max connections, etc.

4b: list all download tasks

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.DownloadStation.Task&version=1&method=list\
&additional=transfer&_sid=$SID" | jq .

includes download/upload speed and progress percentage with &additional=transfer.

4c: add download task (URL)

curl -s -X POST \
  -d "api=SYNO.DownloadStation.Task&version=1&method=create\
&uri=https://example.com/file.zip&_sid=$SID" \
  "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi"

returns: taskid if successful

4d: add download task (torrent file)

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://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi"

returns: taskid if successful

4e: pause a download task

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.DownloadStation.Task&version=1&method=pause\
&id=<TASK_ID>&_sid=$SID"

4f: resume a download task

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.DownloadStation.Task&version=1&method=resume\
&id=<TASK_ID>&_sid=$SID"

4g: delete a download task

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.DownloadStation.Task&version=1&method=delete\
&id=<TASK_ID>&force_complete=false&_sid=$SID"

parameters:

• id - task ID (comma-separated for multiple: task1,task2,task3)
• force_complete - false keeps downloaded files; true cleans them up

step 5: query system information

input: SYNOLOGY_HOST, SYNOLOGY_PORT, SID

output: JSON with system specs and status

5a: get DSM system info

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.DSM.Info&version=2&method=getinfo&_sid=$SID" | jq .

returns: NAS model, RAM, serial number, DSM version, uptime, system temperature

5b: get storage/volume info

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.Storage.CGI.Storage&version=1&method=load_info&_sid=$SID" | jq .

returns: volume names, total capacity, used space, RAID status

5c: get network info

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.DSM.Network&version=1&method=list&_sid=$SID" | jq .

returns: IP addresses, MAC addresses, interfaces (eth0, eth1, etc.)

step 6: cleanup and logout

input: SYNOLOGY_HOST, SYNOLOGY_PORT, SID

output: logout confirmation

when done with all operations, always logout to clean up the session:

curl -s "http://$SYNOLOGY_HOST:$SYNOLOGY_PORT/webapi/entry.cgi?\
api=SYNO.API.Auth&version=6&method=logout\
&session=FileStation&_sid=$SID"

if logout fails, the session will auto-expire after ~15 minutes of inactivity anyway.

decision points

if the user has not provided env vars:

• ask for SYNOLOGY_HOST, SYNOLOGY_PORT, SYNOLOGY_USER, SYNOLOGY_PASS before proceeding
• offer to use defaults (host: 192.168.1.100, port: 5000) only if user confirms

if login fails with error code 406 (2FA required):

• ask the user for their 6-digit OTP code
• re-run login with &otp_code=<CODE> appended to the login URL
• proceed normally once authenticated

if any API call returns error code 106 (session timeout) or 107 (session interrupted):

• automatically re-authenticate (re-run step 1)
• retry the failed operation with the new SID
• do not prompt the user unless re-auth also fails

if FileStation or DownloadStation APIs return error code 102 (no such API):

• the requested package is not installed on the NAS
• suggest the user install it via DSM control panel, or offer an alternative operation
• do not retry the call

if a file upload returns error code 105 (no permission):

• the user account lacks write permission to that folder
• suggest the user check folder permissions in DSM
• offer to list available shared folders instead

if a download task returns error code 105 or 101:

• the URL is invalid, the torrent file is malformed, or DownloadStation is disabled
• ask the user to verify the URL or file and retry
• if DownloadStation is disabled, ask the user to enable it in DSM

if network timeout occurs (curl hangs > 30 seconds):

• the NAS is unreachable or network is slow
• ask the user to verify the hostname/IP and network connectivity
• offer to retry with a longer timeout (add --max-time 60 to curl)

if a search or multi-file operation returns a taskid:

• the operation is running asynchronously
• poll the status endpoint with method=status&taskid=<id> in a loop until "finished": true
• check the response every 2-5 seconds to avoid rate-limiting

if the user wants to list files but does not specify a folder path:

• run step 3a (list root shares) first to show available folders
• then ask which folder the user wants to browse

output contract

all API responses follow this format:

{
  "success": true,
  "data": { /* varies by endpoint */ },
  "error": { "code": 0 }
}

login response (success):

{"data": {"sid": "SESSION_ID_STRING"}, "success": true}

file list response (success):

{
  "success": true,
  "data": {
    "files": [
      {"name": "file.txt", "path": "/volume1/homes/file.txt", "isdir": false, "size": 1024, "mtime": 1234567890},
      {"name": "folder", "path": "/volume1/homes/folder", "isdir": true}
    ],
    "total": 42
  }
}

download list response (success):

{
  "success": true,
  "data": {