Synology DSM API

Synology DSM exposes APIs for system management and file operations.

Overview

Base URL

https://nas-01.inside.domusdigitalis.dev:5001/webapi/

Auth

Session-based (login first)

Format

JSON

2FA

Required for admin operations via API

Key APIs

API Purpose

SYNO.API.Auth

Authentication

SYNO.Core.System

System info, status

SYNO.Core.Share

Shared folder management

SYNO.FileStation.*

File operations

SYNO.Backup.*

Backup tasks

Examples

Login

# Get session ID
curl -ks "https://$NAS_HOST:5001/webapi/auth.cgi?api=SYNO.API.Auth&version=3&method=login&account=$NAS_USER&passwd=$NAS_PASS&format=sid" | jq

# With OTP (2FA)
curl -ks "https://$NAS_HOST:5001/webapi/auth.cgi?api=SYNO.API.Auth&version=3&method=login&account=$NAS_USER&passwd=$NAS_PASS&otp_code=123456&format=sid" | jq

System Info

# netapi
netapi synology system-info

# curl
curl -ks "https://$NAS_HOST:5001/webapi/entry.cgi?api=SYNO.Core.System&version=1&method=info&_sid=$SID" | jq

List Shares

# netapi
netapi synology list-shares

# curl
curl -ks "https://$NAS_HOST:5001/webapi/entry.cgi?api=SYNO.Core.Share&version=1&method=list&_sid=$SID" | jq

Create Folder

# netapi
netapi synology mkdir k3s prometheus

# curl
curl -ks "https://$NAS_HOST:5001/webapi/entry.cgi?api=SYNO.FileStation.CreateFolder&version=2&method=create&folder_path=/k3s&name=prometheus&_sid=$SID"

SSH Alternative for Share Creation

Share creation via API requires 2FA. SSH bypasses this:

# SSH to NAS (bypasses 2FA for share creation)
ssh admin@nas-01

# Create directory
sudo mkdir -p /volume1/k3s/prometheus

# Create share (synoshare CLI)
sudo synoshare --add k3s "k3s Storage" /volume1/k3s "" "" ""

# Set permissions
sudo chown -R 1000:1000 /volume1/k3s

Logout

curl -ks "https://$NAS_HOST:5001/webapi/auth.cgi?api=SYNO.API.Auth&version=1&method=logout&_sid=$SID"

Available APIs

# Key Synology APIs:
# SYNO.API.Auth - Authentication
# SYNO.Core.System - System info, status
# SYNO.Core.Share - Shared folder management
# SYNO.FileStation.* - File operations
# SYNO.Backup.* - Backup tasks

Environment Setup

# Load from dsec
dsource d000 dev/storage

# Or manually
export NAS_HOST="nas-01.inside.domusdigitalis.dev"
export NAS_USER="admin"
export NAS_PASS="<from gopass>"

Learnings

Synology API Gotchas

  • Session-based auth - must login first to get _sid

  • 2FA/OTP required for admin operations (share creation)

  • SSH workaround using synoshare CLI bypasses 2FA

  • netapi synology --otp 123456 share-create supports OTP

  • Port 5001 for HTTPS API access