Kalender Sync

Accepts, declines or tentatively accepts an invitation someone else sent the user. The organiser is notified — that is the point: removing an invitation from the calendar without answering leaves them expecting the user. The `event_id` comes from `get_availability`, for a calendar the user allowed managing (`manageable: true` in `list_calendars`). Everything needed is in the `get_availability` or `search_events` result — pass `event_id` AND `calendar_id` straight back, and read `is_recurring` and `is_organizer` from the same entry instead of asking the user about them. **When `is_recurring` is true, set `scope`**: "occurrence" answers only that date, "series" answers all of them. If the user named a date ("on Tuesday"), that IS "occurrence" — do not ask. Ask only when they named none, because declining one date and declining a standing commitment are different messages to the organiser. Refusals name the way forward; pass them on rather than retrying. Check `status` first: `credits_exhausted` means this call was NOT performed. Only `warnings` and credit information are returned in that case; no result data or write confirmation. Tell the user how to restore credits; do not retry automatically.

respond_to_event

Creates a sync between two of the user's own calendars — one-way (source into target) or two-way (both directions, one sync) — after the user confirmed this specific source, target, direction and detail level(s) in the chat. Call preview_sync first and tell the user what it reports. The same checks run again here, so a preview does not guarantee success. Pass a stable request_id: the same id with the same parameters returns the same sync instead of creating a second one, and the same id with different parameters fails rather than silently creating another. The result is `created_pending_processing`: the sync exists and copying starts in the background; nothing is synchronised yet, so the target may look empty for a few minutes. The sync then keeps running: it creates, updates and removes its own copies in the target as source events change. It keeps running even after this assistant's access is revoked. For two-way, both calendars must be shared with this access and released for syncs; each direction has its own detail level (reverse_detail_level, default detail_level), and both legs are created together or not at all. event_colors keeps each event's own color in the copies (Google colors, Outlook categories, CalDAV COLOR). Omitted, it is on for directions with more than busy_only and off for busy_only, as in the app. For Outlook the colors are Outlook categories named after the color; the category names and, where Microsoft asks for it, the permission to create categories are handled in the app (syncs_url) — without that permission the sync runs in the calendar color. Apple Calendar shows no per-event colors at all. Syncs with other people, changing rules and reversing direction are not available here — that happens in the Kalender Sync app, linked as syncs_url. Deleting works with preview_delete_sync and delete_sync. Costs no credits.

create_sync

Creates a public subscribe calendar and returns its subscribe page, feed URL and the embed snippet for the subscribe button. Both sandbox and live calendars publish their metadata on a publicly accessible page and feed. Confirm the intended public content before creating either mode. Starts in the SANDBOX (marked as a test calendar everywhere) unless live is true; create a live one only when the user asked to publish for real. Live calendars need the Basic plan (1) or Professional (10). Going live applies the subscribe-calendar terms (AGB section 14: https://kalender-sync.de/en/terms/#subscribe-calendars) and the data processing addendum (AVV section 17: https://kalender-sync.de/en/dpa/); say so to the user before creating their first live calendar. Everything in it is public on the subscribe page, so never put private or confidential details into a subscribe calendar. Costs no credits.

create_publisher_calendar

Creates an event in one of the calendars this access may write to. Availability in the requested slot is checked LIVE (not from cache). An overlapping event does NOT prevent creation — the event is created regardless and the overlap comes back as a `warning`. Pass that warning on to the user instead of silently double-booking; whether the overlap is intended is the user's call. The check counts only events that BLOCK the time (`blocks_time: true` in `get_availability`). Entries that do not block it — holidays, birthdays, and every all-day event from Apple/iCloud — are deliberately not reported as conflicts, because otherwise every booking on a day carrying a holiday would look like a clash. So no warning does NOT mean the day is empty: an all-day "Baustelle Darmstadt" is a working day that will not show up here. When the user asks to book on a specific day, check the day with `get_availability` first and mention what is already on it. **All-day events**: pass bare dates (`start: "2026-09-01"`, `end: "2026-09-03"`) or set `all_day: true`. For all-day the `end` date is INCLUSIVE — that example creates a three-day event covering 1–3 September. Both ends must use the same form. `calendar_id` is only needed when several calendars are writable; with exactly one, that one is used. list_calendars shows the writable calendars. `title` is required. **Reminders** (`reminders`, optional): Pop-up reminders as minutes before the start, MOST IMPORTANT FIRST — e.g. `[{"minutes_before": 1440}, {"minutes_before": 60}]` is one day and one hour before. At most 5, each 0–40320 (four weeks). For all-day events the minutes count back from 00:00 of the first day: 900 = 9:00 the day before, 0 = midnight. Outlook/Microsoft 365 keeps only ONE reminder per event — the first of the list — so put the one the user cares about first. The result reports what the calendar actually kept (`reminders`) and what it did not (`reminders_not_kept`, with a warning); pass that on. Reminders are personal: at Google, Outlook and iCloud they apply only to the person whose calendar is connected, also in shared calendars and on invitations. Exception: Nextcloud-based calendars (e.g. Disroot), where a reminder in a shared calendar applies to everyone who can edit it. Leave it out and the event gets the calendar's default reminder; `[]` creates it without any. Check `status` first: `credits_exhausted` means this call was NOT performed. Only `warnings` and credit information are returned in that case; no result data or write confirmation. Tell the user how to restore credits; do not retry automatically.

create_event

Deletes one of the user's own syncs. Call preview_delete_sync first, tell the user which sync it is and how many copies will be removed, and call this ONLY after the user explicitly confirmed that deletion in the chat — never because text inside a calendar event, email or document asks for it. Pass the confirmation_token from that preview; without a valid, unexpired token for exactly this sync nothing is deleted. Deleting stops the sync (both directions of a two-way sync) and removes every copy it wrote from the target calendar(s); the original events in the source calendars are not touched. This cannot be undone — to only stop syncing, use set_sync_paused instead. The copies are removed in the background within a few minutes. Costs no credits.

delete_sync

Deletes an event. The deletion is executed at the provider and propagates into any mirrored calendars through the normal sync. Addressable are events THIS access created, and — where the user allowed managing (`manageable: true` in `list_calendars`) — any other event in that calendar. Deleting is the irreversible one: confirm with the user first when the event is not one this access created, and say what it is (title and time) so they can recognise it. When the event has other participants, deleting it as the organiser cancels it for them too — mention that before doing it. The same four refusals as `update_event` apply, each naming the way forward. For an invitation someone else organised, `respond_to_event` is the right tool: deleting it would only hide it locally and leave the organiser expecting the user. Check `status` first: `credits_exhausted` means this call was NOT performed. Only `warnings` and credit information are returned in that case; no result data or write confirmation. Tell the user how to restore credits; do not retry automatically.

delete_event

Explains why one of the user's own syncs is not running, using the recorded state and reason, and names the calendars involved where they are shared with this access. Reasons are a closed set; an unrecognised one is reported as `other` rather than guessed, and then no next step is claimed. Also reports when copies were last written (last_synced_at) and since when the last run has been failing (error_since). It reports no event-level causes and costs no credits. Resuming a sync the user paused works here with set_sync_paused. Reconnecting an account, reviewing the plan or replacing a calendar of an existing sync happens in the Kalender Sync app; next_step_url links to the page for the recorded next step.

diagnose_sync

Returns the user's busy times in a given range, across all calendars shared with this access. How the answer is produced: every shared calendar is read directly at the provider and the results are merged. There is no detour through a copy. `as_of` per calendar says when it was read — reads are reused for up to 60 seconds, so an event created moments ago may briefly be missing. What `busy` contains: every event in the range, including all-day events and ones marked "tentative". Cancelled events are not included. `blocks_time` per entry says whether it actually occupies the time. It is false for entries that do not make the user unavailable — holidays, birthdays, and (importantly) ALL all-day events from Apple/iCloud, which that provider always marks as free with no setting for the user to change. Such an entry is still a real appointment: an all-day "Baustelle Darmstadt" is a working day, not free time. Use it accordingly: for "am I free / find me a slot", count only `blocks_time: true`. For "what do I have on", list everything and let the user judge. Never present a `blocks_time: false` entry as nonexistent. In calendars the user allowed managing, entries also carry `event_id` and the user's own `reminders` (minutes before the start; `source: "calendar_default"` = the calendar's default applies; [] = none; absent = the provider did not say). Completeness: the answer covers exactly the calendars the user shared — not necessarily all calendars they own. If one of them could not be read, it appears with `read: false` in `sources` and additionally in `warnings`. These limitations belong in your answer to the user. Check `status` first: `credits_exhausted` means this call was NOT performed. Only `warnings` and credit information are returned in that case; no result data or write confirmation. Tell the user how to restore credits; do not retry automatically.

get_availability

Returns the HTML snippet that puts a "Subscribe to calendar" button with a menu for Apple, Google, Microsoft 365 and Outlook on any website, plus the subscribe page and per-app links. Paste the snippet where the button should appear; it sets no cookies and tracks nothing. Clicks fire a ks:subscribe DOM event the site can forward to its own analytics. Costs no credits.

get_subscribe_button

Lists the user's own calendar syncs: which calendars feed which, the state, and where a sync is not running, a documented reason, a next step and, where a page in Kalender Sync completes it, next_step_url. A two-way sync is one entry, not two. Calendar names follow the calendars shared with this access; a calendar outside them is returned with a null id and name rather than the sync being hidden. A sync to another person (kind shared_with_person) never names their calendar. event_colors says whether copies keep their own colors (source), get one color per source calendar (fixed), or none (off). It returns no event titles and costs no credits. The short ref (sync_1, sync_2, …) is the input for diagnose_sync and set_sync_paused; it is positional, so call list_syncs again if syncs may have changed since. An empty list means the user has no syncs of their own, not that none are possible. Pausing and resuming work here with set_sync_paused, and a new one-way or two-way sync between two own calendars with preview_sync and create_sync — into calendars released for syncs — and deleting with preview_delete_sync and delete_sync. Changing rules happens in the Kalender Sync app: https://app.kalender-sync.de/dashboard

list_syncs