Syno

The Syno API is organized into several service-specific classes, accessible via short aliases on the syno instance:

To use the Syno API in JavaScript or TypeScript, import the Syno class and instantiate it with a configuration object. All API methods return Promises.

import { Syno } from 'syno';

const syno = new Syno({
    protocol: 'https',
    host: 'localhost',
    port: 5001,
    account: 'my_username',
    passwd: 'my_password',
    apiVersion: '7.2',
});

// Using a method directly
const info = await syno.fs.getInfo();

// Calling a method dynamically
const info = await syno.fs.call('getInfo', { folder_path: '/path' });

If you are upgrading from version 2.x, note the following breaking changes:

• Async/await only: All methods now return Promises. Callbacks are no longer supported.
• Node.js 24+ required: Uses native fetch.
• Browser support removed: Node.js only.
• Default API version: Changed from 6.0.2 to 7.2.
• DSM 5.x support dropped: Only 6.x and 7.x definitions are included.
• Module System: Supports both ESM (import) and CJS (require).
• TypeScript: Types are included in the package; no separate @types package is needed.

To use Syno as a Node.js library in your project, install it via npm:

npm install syno

Requirements:

• Node.js >= 24.0.0 (uses native fetch)

To install the command-line interface (CLI) globally:

npm install -g syno

The AuthenticatedAPI class is the base for all service-specific APIs in Syno that require authentication (e.g., DSM, File Station, Download Station). It manages session state automatically by checking for an existing session SID in the AuthenticatedAPIHost.

If a valid session SID is found for the requested sessionName, it is automatically appended to the request parameters as _sid. If no session exists, the class performs an auto-login via this.syno.auth.login(sessionName), stores the resulting SID in the sessions map, and then proceeds with the original request.

Syno uses a modular architecture where specific services are accessed via dedicated station classes. The following modules are exported and available through the client:

• DSM: Core DSM functionality.
• FileStation: File management and enumeration.
• DownloadStation: Managing download tasks.
• AudioStation: Audio management.
• VideoStation: Video management.
• VideoStationDTV: DTV-specific video features.
• SurveillanceStation: Surveillance and camera management.
• SynologyPhotos: Photo management and organization.

When instantiating new Syno(), you can provide the following configuration options:

The project uses a default configuration directory and file to persist settings:

• Directory: ~/.syno (in the user's home directory)
• File: config.yaml

Use ensureDefaultConfig() to automatically create this directory and a template config.yaml if they do not exist. This is useful for initializing a local environment for the CLI.

import { ensureDefaultConfig } from '../src/cli/config.js';

const configPath = ensureDefaultConfig();
console.log(`Config is located at: ${configPath}`);

The syno CLI allows you to execute Synology DSM API methods directly from your terminal. The command structure follows a pattern of syno <station> <method> [options].

Each station corresponds to a specific Synology service (like File Station or Download Station). You must provide the name or alias of the station followed by the specific API method you wish to call.

# Example: Calling a method on File Station
syno fs list_folder --payload '{"path": "/volume1/homes"}'

# Example: Using an alias for Download Station
syno dl get_task_list

If you encounter Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE when using https, you can bypass certificate verification using one of these methods:

CLI Flag:

syno fs getInfo --ignore-certificate-errors

Environment Variable:

export SYNO_IGNORE_CERTIFICATE_ERRORS=1

Code Configuration:

const syno = new Syno({
    ignoreCertificateErrors: true,
    // ...
});

You can override connection settings and behavior using the following environment variables. These take precedence over configuration files but are overridden by explicit CLI options.