Calendar
Overview
Synology Calendar API client.
Manages calendars, events, tasks, settings, and timezone information via the SYNO.Cal.* WebAPI endpoints.
Requires Synology Calendar 2.5.0+ on the target NAS.
Methods
cal_create
Create a calendar or task list.
Internal API
SYNO.Cal.Cal
Parameters
cal_type str
"event" for calendar, "todo" for task list.
cal_displayname str
Calendar display name.
cal_description str
Calendar description.
cal_color str
Calendar colour in RGB hex, e.g. "#FF8000".
is_hidden_in_cal bool
Hide events for this calendar (default False).
is_hidden_in_list bool
Hide calendar from list (default False).
notify_alarm_by_browser bool
Send reminder via browser (default True).
notify_alarm_by_mail bool
Send reminder via email (default True).
notify_evt_by_browser bool
Send event changes via browser (default True).
notify_evt_by_mail bool
Send event changes via email (default False).
notify_import_cal_by_browser bool
Send import results via browser (default True).
notify_import_cal_by_mail bool
Send import results via email (default True).
Returns
dict[str, object] or str
Created calendar object with cal_id.
cal_list
List calendars and/or task lists.
Internal API
SYNO.Cal.Cal
Parameters
cal_type str
"event", "todo", or "all" (default "all").
Returns
dict[str, object] or str
{"data": {"list": [...]}, "success": True}.
cal_get
Get a single calendar by ID.
Internal API
SYNO.Cal.Cal
Parameters
cal_id str
Calendar ID, e.g. "/admin/home/".
Returns
dict[str, object] or str
Calendar object.
cal_set
Edit calendar information.
Internal API
SYNO.Cal.Cal
Parameters
cal_id str
Calendar ID, e.g. "/admin/home/".
cal_type str
"event" for calendar, "todo" for task list.
original_cal_id str
Calendar's original ID.
cal_displayname str
Calendar display name.
cal_description str
Calendar description.
cal_color str
Calendar colour in RGB hex, e.g. "#E3BD00".
is_hidden_in_cal bool
Hide events for this calendar (default False).
is_hidden_in_list bool
Hide calendar from list (default False).
notify_alarm_by_browser bool
Send reminder via browser (default True).
notify_alarm_by_mail bool
Send reminder via email (default True).
notify_evt_by_browser bool
Send event changes via browser (default True).
notify_evt_by_mail bool
Send event changes via email (default False).
notify_import_cal_by_browser bool
Send import results via browser (default True).
notify_import_cal_by_mail bool
Send import results via email (default True).
Returns
dict[str, object] or str
Updated calendar object.
cal_delete
Delete a calendar.
Internal API
SYNO.Cal.Cal
Parameters
cal_id str
Calendar ID.
Returns
dict[str, object] or str
{"success": True} on success.
event_create
Create a new event.
Internal API
SYNO.Cal.Event
Parameters
cal_id str
Calendar ID, e.g. "/admin/home/".
original_cal_id str
Calendar's original ID.
summary str
Event title.
is_all_day bool
Whether this is an all-day event.
tz_id str
Timezone ID, e.g. "Europe/Rome".
Use :meth:timezone_list to discover available values.
dtstart int
Event start time in Epoch seconds.
dtend int
Event end time in Epoch seconds.
is_repeat_evt bool
Whether this is a recurring event (default False).
repeat_setting dict
Recurrence rule configuration (see API guide for repeat_obj).
color str
Event colour as #RRGGBB hex, e.g. "#00FF00".
Defaults to "#000000" (black). Required on Calendar 3.x.
notify_setting list[dict]
Notification settings (see API guide for notify_obj).
description str
Event description. Defaults to a single space for Calendar 3.x
compatibility (requires a non-empty value).
participant list[dict]
Event participants (see API guide for participant_obj).
location_info dict
Location information (see API guide for location_obj).
from_syno_app_url dict
Source Synology app (e.g. MailPlus).
Returns
dict[str, object] or str
Created event object with evt_id.
event_list
List events with optional filters.
At least one of start, end, or limit is required
by the API.
Internal API
SYNO.Cal.Event
Parameters
cal_id_list list[str]
Calendar IDs to filter by.
start int
Start time in Epoch seconds.
end int
End time in Epoch seconds.
evt_color_list list[str]
Event colours to list, e.g. ["#112233", "#445566"].
keyword str
Search keyword in summary, description, and location.
limit int
Maximum number of events to return.
filter_starred str
"yes", "no", or "all" (default "all").
filter_own str
"yes", "no", or "all" (default "all").
filter_invited str
"yes", "no", or "all" (default "all").
Returns
dict[str, object] or str
{"data": {"list": [...]}, "success": True}.
event_get
Get event or sub-event details.
Use either evt_id or ical_uid (mutually exclusive).
When using ical_uid, cal_id must also be provided.
Internal API
SYNO.Cal.Event
Parameters
evt_id int
Event ID.
recurrence_id str
Sub-event date in ISO 8601 format (YYYYMMDD or
YYYYMMDDThhmmss).
ical_uid str
Event UID within ICS. Mutually exclusive with evt_id.
cal_id str
Calendar ID. Required when using ical_uid.
Returns
dict[str, object] or str
Event object.
event_set
Modify an event. Returns main event info on success.
.. warning::
On Calendar 3.x, personal_property and location_info
must be passed explicitly for the set method to succeed.
Internal API
SYNO.Cal.Event
Parameters
evt_id int
Event ID.
cal_id str
Calendar ID.
original_cal_id str
Calendar's original ID.
dav_etag str
Event timestamp (optimistic locking).
If this differs from the server value, someone else
already modified the event.
summary str
Event title.
is_all_day bool
Whether this is an all-day event.
tz_id str
Timezone ID, e.g. "Europe/Rome".
dtstart int
Event start time in Epoch seconds.
dtend int
Event end time in Epoch seconds.
is_repeat_evt bool
Recurring event (default False).
repeat_setting dict
Recurrence rules.
color str
Event RGB colour.
notify_setting list[dict]
Notification settings.
description str
Event description.
participant list[dict]
Event participants.
location_info dict
Location information.
attachments list[dict]
Attachment information.
exdate str
Delete a specific occurrence of a recurring event
(ISO 8601 format).
Returns
dict[str, object] or str
Updated event object.
event_delete
Delete an event.
Internal API
SYNO.Cal.Event
Parameters
evt_id int
Event ID.
Returns
dict[str, object] or str
{"success": True} on success.
todo_create
Create a task.
Internal API
SYNO.Cal.Todo
Parameters
original_cal_id str
Calendar's original ID for the task list.
summary str
Task title.
is_all_day bool
All-day task (default False).
tz_id str
Timezone ID, e.g. "Europe/Rome".
has_start_time bool
Whether the task has a start time (default False).
dtstart int
Start time in Epoch seconds (0 = not set).
has_end_time bool
Whether the task has a due date (default False).
due int
Due date in Epoch seconds (0 = not set).
notify_setting list[dict]
Notification settings.
description str
Task description. Defaults to a single space for Calendar 3.x
compatibility (requires a non-empty value).
percent_complete int
Completion percentage: 0 or 100 (default 0).
from_syno_app_url dict
Source Synology app.
Returns
dict[str, object] or str
Created task object with evt_id.
todo_set
Modify a task.
.. warning::
On Calendar 3.x, description must be non-empty (default " ")
and notify_setting may need to be passed explicitly.
Internal API
SYNO.Cal.Todo
Parameters
evt_id int
Task ID.
original_cal_id str
Calendar's original ID for the task list.
dav_etag str
Task timestamp (optimistic locking).
summary str
Task title.
is_all_day bool
All-day task (default False).
tz_id str
Timezone ID.
has_start_time bool
Has start time (default False).
dtstart int
Start time in Epoch seconds (0 = not set).
has_end_time bool
Has due date (default False).
due int
Due date in Epoch seconds (0 = not set).
notify_setting list[dict]
Notification settings.
description str
Task description. Defaults to a single space for Calendar 3.x
compatibility (requires a non-empty value).
percent_complete int
Completion: 0 or 100 (default 0).
priority_order int
Task priority.
Returns
dict[str, object] or str
Updated task object.
todo_list
List tasks.
Internal API
SYNO.Cal.Todo
Parameters
cal_id_list list[str]
Task list IDs to filter by.
due int
Due date timestamp in Epoch seconds.
filter_complete str
"yes", "no", or "all" (default "all").
filter_due str
"yes", "no", or "all" (default "all").
limit int
Maximum number of tasks to return.
Returns
dict[str, object] or str
{"data": {"list": [...]}, "success": True}.
todo_get
Get task details.
Internal API
SYNO.Cal.Todo
Parameters
evt_id int
Task ID.
Returns
dict[str, object] or str
Task object.
todo_delete
Delete a task.
Internal API
SYNO.Cal.Todo
Parameters
evt_id int
Task ID.
Returns
dict[str, object] or str
{"success": True} on success.
setting_get
Get calendar user settings.
Internal API
SYNO.Cal.Setting
Returns
dict[str, object] or str
User configuration with date format, default calendar,
timezone, etc.
setting_set
Modify calendar user settings.
Only the parameters you provide will be updated.
Internal API
SYNO.Cal.Setting
Parameters
date_format str
"Y-m-d", "m/d/Y", "d/m/Y",
"d.m.Y", or "d-m-Y".
default_alarm dict
Default reminder for partial-day events.
default_alarm_ad dict
Default reminder for all-day events.
default_cal str
Default calendar ID for new events.
default_plugin_mode str
"nav_panel" or "todo_plugin".
default_todo_view dict
Default task list view configuration.
default_view str
"day", "week", "month", or "list".
enable_keyboard_shortcut bool
Enable keyboard shortcuts.
last_used_map_type str
"none", "google", or "baidu".
show_week_numbers bool
Show week numbers.
time_format str
"12" or "24".
time_zone str
Default timezone, e.g. "Europe/Rome".
week_start_day int
0=Sunday, 1=Monday, …, 6=Saturday.
Returns
dict[str, object] or str
Updated user configuration.
timezone_list
List available timezone IDs.
Internal API
SYNO.Cal.Timezone
Returns
dict[str, object] or str
{"data": {"list": [{"tzid": "Europe/Rome", ...}, ...]}, "success": True}.
contact_list
List calendar contacts (invitees).
Internal API
SYNO.Cal.Contact
Parameters
list_dsm_only bool
List only DSM users (default False).
Returns
dict[str, object] or str
{"data": {"list": [...]}, "success": True}.