synology-api is a Python wrapper over the Synology DSM interface

One class per DSM service

synology-api is a Python wrapper around the Synology API, and the design is the obvious one for a NAS that exposes many separate service endpoints. Each DSM feature becomes a class, so file management is a FileStation object and downloads are a DownloadStation object, and the two are used side by side in the readme's basic example. The two classes are constructed with the same arguments and then asked for their own info method, which makes the shape of the library clear from the first example.

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

The alternative to a wrapper is to write the request construction, the authentication handshake and the error handling yourself for every endpoint, which is exactly the work this library exists to remove. The scale of that work is stated in the readme, which says there are around three hundred APIs implemented with countless methods for each, and that the majority are not documented although some are. An exhaustive list of the supported APIs is published in the documentation, so the coverage is knowable even where the details are not written down.

The constructor is verbose and explicit

Constructing a client takes the device address and port, the credentials, and a set of switches. The readme example passes the host, the port, the username, the password, and then the options, which include whether the connection is secure, whether the certificate is verified, the DSM version, a debug flag and an optional one time password code.

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

Three of those options are worth attention before you use the library. The DSM version is an explicit argument rather than something negotiated, which is the right design if the API surface differs between releases, but it means you have to know which version your NAS runs. The certificate verification switch in the example is off, which is convenient for a self signed certificate on a home NAS and is the wrong default for anything else. And the one time password code, which is how you log in when the NAS requires a two step code, is passed in the constructor rather than being fetched interactively, so it has to be supplied on each construction.

QuickConnect removes the fixed address problem

For devices that are not reachable on a fixed address, the library offers a second construction path. For NAS devices reachable through QuickConnect you pass the QuickConnect identifier instead of an IP address and a port, and the connection uses HTTPS automatically, since the identifier is a service name rather than an address.

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

This is a small feature with a large practical effect, because a NAS that is behind a dynamic address or on a network you do not control is otherwise awkward to script, and the alternative of a VPN or a tunnel is more setup than most home users want. The security switch appears here too, and it is worth noting that with QuickConnect the traffic is encrypted to the Synology relay service rather than directly to the device, which is a different trust model from a direct connection on your own network.

The async client is a wrapper, not a rewrite

The beta addition is an async client, and the readme describes it in one sentence, which is the interesting part. Every existing synology-api class can be made async with a single wrapper and no extra dependencies, so there is no separate async implementation to maintain and no new library to learn.

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))
    info = await fs.get_info()
    files = await fs.get_file_list("/home")
    a, b, c = await asyncio.gather(
        fs.get_file_list("/home"),
        fs.get_file_list("/photo"),
        fs.get_file_list("/music"),
    )

asyncio.run(main())

The value of it is visible in the last block, since gathering several directory listings concurrently is the kind of thing that turns a slow home automation script into a responsive one, and doing it with the standard asyncio primitives rather than a separate framework keeps the dependency list unchanged. The label on it is beta, and the documentation for it lives in its own section of the site, so treat the async surface as the least settled part of the library.

A hobby project that says so

The readme is unusually direct about its own status, and that is a good thing to read before you build on it. The author says he does this for hobby, as a passion, in his little free time, that there are no warranties chained, and that the library is provided as is. He also says you will find many things that can be simplified, and that he slowly will but invites contributions. The premises section is similarly practical, saying the wrapper was only tried with Python 3 and that he does not know whether it runs on previous versions, and asking people to do their own research before opening an issue. The conclusion section says there is still a lot to implement, that the code is probably twisted in some parts, and that he will try to optimise it. None of that is a defect. For a library that wraps a vendor API, the rate of change in the vendor's own interface is the dominant factor, and a maintainer with a day job is arguably better placed to track it than a vendor.

Packaging, tooling and the community around it

The packaging is old-fashioned and readable, with a setup script that reads the readme for the long description, finds the packages, declares the MIT licence and lists the runtime dependencies, which are requests, urllib3, setuptools, requests_toolbelt, tqdm, cryptography, treelib and noiseprotocol. The requirements file pins the same set exactly, plus a few development extras such as psutil, PyYAML and a docstring parser. The development tooling around it is worth noting, since it says how the documentation is produced, with a mustache template for docstrings, a documentation directory, a documentation status configuration, a Taskfile for the task runner, a tool versions file, a pre-commit configuration, a contributor covenant, a contributing guide and a security policy. The community is arranged around a Telegram group and GitHub discussions, and there is a list of related projects by the same author, a Telegram bot built on the library, a Home Assistant integration, and a Model Context Protocol server, which is the clearest evidence that the library is used as a foundation rather than as a script collection. The manifest version sits slightly ahead of the newest tagged release, and the last push was on 2026-10-15.

Editorial conclusion

synology-api suits a home automation project that needs to read or write on a Synology NAS from a script, since the class per service model means the API surface of a DSM feature is one object, and the QuickConnect and one time password options remove the two usual obstacles. It is a poor choice for a production integration that needs a support commitment, since the author states the code is provided as is with no warranties chained, and it is a poor choice if you depend on documented behaviour, since the readme says most of the several hundred methods are not documented. Verify three things before you depend on it: which DSM version your NAS runs, since the version is a constructor argument and the project is tested against a particular line, whether your deployment can accept the certificate verification default, which the examples turn off, and how much of the API you actually need documented, since the exhaustive list is a table of names rather than reference documentation. The licence is MIT, the newest release is v0.9.4, and the last push was on 2026-10-15.

Frequently asked questions

Official sources

1. License: MIT
2. N4S4/synology-api on GitHub
3. Project website
4. README
5. Releases