OpenParable
Skip to content
← Back to skills

Synology API

Apps & Automation
synology-api

Synology API is an Agent Skill for apps & automation published in the tympanix/Electorrent repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Synology Download Station Web API reference covering API discovery, authentication, request format, common errors, and Download Station task operations.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/tympanix/Electorrent/blob/HEAD/.github/skills/synology-api/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/synology-api, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

CodeMeaning
100Unknown error
101Invalid parameter
102Requested API does not exist
103Requested method does not exist
104Requested version does not support the functionality
105Logged-in session does not have permission
106Session timeout
107Session interrupted by duplicate login

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:

CodeMeaning
400No such account or incorrect password
401Account disabled
402Permission denied
4032-step verification code required
404Failed to authenticate 2-step verification code

Download Station API families

APIPurpose
SYNO.DownloadStation.InfoPackage info and settings
SYNO.DownloadStation.ScheduleSchedule settings
SYNO.DownloadStation.TaskList tasks and perform task actions
SYNO.DownloadStation.StatisticTotal download/upload stats
SYNO.DownloadStation.RSS.SiteRSS site list/refresh
SYNO.DownloadStation.RSS.FeedRSS feed list
SYNO.DownloadStation.BTSearchBT search operations

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:

CodeMeaning
400File upload failed
401Max number of tasks reached
402Destination denied
403Destination does not exist
404Invalid task id
405Invalid task action
406No default destination
407Set destination failed
408File does not exist

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