Synology API

Skill: Synology Download Station API

Purpose

Use this skill when you need to integrate with Synology DSM Download Station through its Web API.

Request format

All requests use /webapi/<CGI_PATH> with these core query parameters:

• api=<API_NAME>
• version=<VERSION>
• method=<METHOD>
• additional method-specific params
• session via _sid=<SID> or cookie

General form:

GET /webapi/<CGI_PATH>?api=<API_NAME>&version=<VERSION>&method=<METHOD>[&<PARAMS>][&_sid=<SID>]

Response format

All responses are JSON objects with:

• success: true or false
• data: method result on success
• error: integer error code on failure

Common error codes

API discovery

Start with SYNO.API.Info.

• fixed path: /webapi/query.cgi
• query available APIs:

/webapi/query.cgi?api=SYNO.API.Info&version=1&method=query&query=ALL

Electorrent specifically needs:

• SYNO.API.Auth
• SYNO.DownloadStation.Task

Authentication

SYNO.API.Auth

• path is discovered from SYNO.API.Info (commonly auth.cgi)
• login:

/webapi/auth.cgi?api=SYNO.API.Auth&version=2&method=login&account=<user>&passwd=<pass>&session=DownloadStation&format=cookie

Important params:

• account
• passwd
• session=DownloadStation
• format=cookie or format=sid
• optional otp_code

Logout:

/webapi/auth.cgi?api=SYNO.API.Auth&version=1&method=logout&session=DownloadStation

Auth-specific error codes:

Download Station API families

SYNO.DownloadStation.Task

list

Request params:

• offset optional, default 0
• limit optional, default -1
• additional optional comma-separated expansions:
  • detail
  • transfer
  • file
  • tracker
  • peer

Example:

/webapi/DownloadStation/task.cgi?api=SYNO.DownloadStation.Task&version=1&method=list&additional=detail,file

Returns:

• total
• offset
• tasks[]

Task objects include fields such as:

• id
• type
• username
• title
• size
• status
• status_extra
• optional additional.detail, additional.transfer, additional.file, additional.tracker, additional.peer

getinfo

Params:

• id=dbid_001,dbid_002
• optional additional=detail,transfer,file,tracker,peer

Returns tasks[].

create

Used to add downloads.

Params:

• uri optional: HTTP / FTP / magnet / ED2K links, or shared-folder file paths
• file optional: uploaded torrent/NZB payload
• username optional
• password optional
• unzip_password optional
• destination optional shared-folder-relative destination

This is typically a POST for uploads.

delete

Params:

• id
• force_complete

Returns per-task result objects containing:

• id
• error (0 means success)

pause

Params:

• id

Returns per-task result objects with id and error.

resume

Params:

• id

Returns per-task result objects with id and error.

edit

Commonly used to change destination.

Params:

• id
• destination

Returns per-task result objects with id and error.

Task error codes

Useful task-specific codes:

Electorrent usage

Electorrent uses:

1. SYNO.API.Info query for API discovery
2. SYNO.API.Auth login
3. SYNO.DownloadStation.Task.list
4. SYNO.DownloadStation.Task.create for URL and file uploads
5. SYNO.DownloadStation.Task.pause
6. SYNO.DownloadStation.Task.resume
7. SYNO.DownloadStation.Task.delete

Reference

• https://global.download.synology.com/download/Document/Software/DeveloperGuide/Package/DownloadStation/All/enu/Synology_Download_Station_Web_API.pdf