Synology Calendar API Skill

Overview

Manage Synology Calendar using the official Calendar API.

Documentation: Calendar_API_Guide_enu.pdf

Connection

Environment Variables

export SYNOLOGY_URL="http://{nas_ip}:5000"  # 内网地址
export SYNOLOGY_USER="{username}"
export SYNOLOGY_PASSWORD="your-password"

Quick Start

from client import SynologyCalendar

cal = SynologyCalendar()
cal.login()

# List calendars
calendars = cal.get_calendars()
for c in calendars:
    print(f"{c['cal_id']}: {c['cal_displayname']}")

cal.logout()

API Reference

Calendar Operations (SYNO.Cal.Cal)

Method	Description	Status
`get_calendars()`	List all calendars	✅ Working
`get_calendar(cal_id)`	Get calendar details	✅ Working
`create_calendar(...)`	Create calendar	✅ Working
`delete_calendar(cal_id)`	Delete calendar	✅ Working

Event Operations (SYNO.Cal.Event)

Method	Description	Status
`list_events(cal_id_list)`	List events	✅ Working
`get_event(evt_id)`	Get event details	✅ Working
`create_event(...)`	Create event	✅ Working
`delete_event(evt_id)`	Delete event	✅ Working

Event Creation Notes:

✅ Working:

All event types now work correctly with v1 API

⚠️ Critical: SID must be in URL parameter, not JSON body

The Synology Calendar v1 API requires the _sid parameter in the URL query string, not in the JSON body.

create_event Parameters:

Parameter	Type	Required	Example
cal_id	string	✅	`/admin/home/`
summary	string	✅	Event title
dtstart	int	✅	1770440000
dtend	int	✅	1770443600
is_all_day	bool	✅	`false`
is_repeat_evt	bool	✅	`false`
color	string	✅	`#D9AE00`
description	string	✅	Description
notify_setting	array	✅	`[]`
participant	array	✅	`[]`
timezone	string	(if not all-day)	`Asia/Shanghai`

Example:

# Non-all-day event (working)
cal.create_event(
    cal_id='/{username}/home/',
    summary='Meeting',
    dtstart=now,
    dtend=now + 3600,
    is_all_day=False,
    is_repeat_evt=False,
    description='Team meeting',
    color='#D9AE00',
    timezone='Asia/Shanghai'
)

Todo Operations (SYNO.Cal.Todo)

Method	Description	Status
`create_todo(...)`	Create task	✅ Working
`list_todos(...)`	List tasks	✅ Working
`get_todo(evt_id)`	Get task details	✅ Working
`delete_todo(evt_id)`	Delete task	✅ Working
`complete_todo(evt_id)`	Mark complete	✅ Working

Contact Operations (SYNO.Cal.Contact)

Method	Description	Status
`list_contacts()`	List participants	✅ Working

synology-calendar

Install via CLI (Recommended)