A Python wrapper around Synology's DiskStation Manager (DSM) API that lets developers script and automate their Synology NAS in Python, aimed at NAS owners and hobbyist developers who want to build tooling on top of their own hardware.

What it is

Synology-api is a Python library that wraps the Synology DSM API, exposing NAS functions as Python classes and methods so a developer can drive a Synology device from a script instead of writing raw API calls by hand. It lives in the Python 3 ecosystem and is distributed as synology-api on PyPI. The README states plainly that the project exists for people who are "trying to develop something for your NAS," and that the wrapper is meant to help build that script. The topic list places it in automation, home automation, and DSM territory, alongside synology-nas, api-wrapper, and python-3.

The concrete problem it solves is the repetitive work of authenticating against DSM and shaping requests and responses for each NAS service. Rather than reimplementing that plumbing per script, a developer imports a class such as FileStation or DownloadStation from synology_api and calls methods on it. Authentication, session handling, and parameters such as secure, cert_verify, dsm_version, debug, and otp_code are handled through the constructor. The library implements around 300 APIs, so it stands in for hand-written integration code across a wide slice of DSM rather than for one narrow endpoint.

Key capabilities

• Ships as the pip3 install synology-api package, and can also be installed from source with pip3 install git+https://github.com/N4S4/synology-api.
• Implements roughly 300 Synology APIs with methods for each, though the majority are undocumented and an exhaustive list lives on the docs site under "Supported APIs."
• Provides service classes including synology_api.filestation.FileStation and synology_api.downloadstation.DownloadStation, with methods such as get_info() and get_file_list().
• Connects either by IP address and port or through a QuickConnect ID, in which case HTTPS is used automatically.
• Accepts otp_code in the constructor, so two-factor authentication can be handled from a script.
• Offers an asynchronous client in beta, synology_api.async_client.AsyncClient, which wraps any existing class to make all its methods awaitable with no extra dependencies.
• Supports parallel calls, for example asyncio.gather() over get_file_list() for several directories at once.

Who uses it and how

• NAS owners who automate file and download operations on their own Synology device, calling FileStation and DownloadStation from a Python script.
• Home automation builders, reflected in the home-automation topic and the related companion project homeassistant-synology-pro.
• Bot authors, indicated by the related synology-api-telegram-bot project listed in the README.
• Users on remote or non-LAN setups who reach the NAS by QuickConnect ID rather than by local IP and port.
• Developers with concurrent workloads, who use AsyncClient with asyncio.gather() to issue several NAS requests in parallel.

Getting started

Install with pip3 install synology-api, or from source with pip3 install git+https://github.com/N4S4/synology-api. Usage examples for synchronous and async clients are documented at https://n4s4.github.io/synology-api/docs/getting-started/usage.

How it compares

No list of paid products this project replaces is provided in the available facts, and the README names no directly comparable client libraries; it names only companion projects, the Telegram bot and the Home Assistant integration, both built by the same author. On that evidence it stands alone in this registry as a Synology-focused Python API wrapper.

When to use it — and when not to

This is a hobby project, as the author states directly: it is provided "As Is," with no warranties, written in the author's free time, and only tested against Python 3, with the further note that much of the code is undocumented and in some parts "twisted." Much of what a self-hoster would operate is therefore the library itself and the docs, not infrastructure such as a database or mail server. Anyone who needs vendor-backed support, complete API documentation, or a stable interface across many hundreds of DSM endpoints should look elsewhere; the 300-odd implemented APIs do not come with documentation for most of them, and the README itself lists "still a lot to implement."

pip3 install synology-api

pip3 install git+https://github.com/N4S4/synology-api

from synology_api.filestation import FileStation
from synology_api.downloadstation import DownloadStation

fs = FileStation(
    'Synology Ip',
    'Synology Port',
    'Username',
    'Password',
    secure=False,
    cert_verify=False,
    dsm_version=7,
    debug=True,
    otp_code=None
)

ds = DownloadStation(
    'Synology Ip',
    'Synology Port',
    'Username',
    'Password',
    secure=False,
    cert_verify=False,
    dsm_version=7,
    debug=True,
    otp_code=None
)

fs_info = fs.get_info()
ds_info = ds.get_info()

fs = FileStation(
    quickconnect_id='QuickConnect ID',
    username='Username',
    password='Password',
    cert_verify=False,
    dsm_version=7,
    debug=True,
    otp_code=None
)

import asyncio
from synology_api.filestation import FileStation
from synology_api.async_client import AsyncClient

async def main():
    fs = AsyncClient(FileStation("192.168.1.x", "5001", "admin", "pass",
                                  secure=True, cert_verify=False, dsm_version=7))

    # All methods automatically awaitable
    info = await fs.get_info()
    files = await fs.get_file_list("/home")

    # Run parallel calls
    a, b, c = await asyncio.gather(
        fs.get_file_list("/home"),
        fs.get_file_list("/photo"),
        fs.get_file_list("/music"),
    )

asyncio.run(main())