Quickstart

A free account is enough for the quickstart. You work with a sandbox key: it creates test calendars that work in real calendar apps but are marked as tests.

1. Create a sandbox key

1. Sign in to the Kalender Sync app or create a free account.
2. Open Settings › Developer / API.
3. Give the key a name and click Create sandbox key.
4. Copy the key. It is shown exactly once.

Put it in an environment variable for the calls below:

export KS_KEY="ks_test_…"

2. Check the key

curl https://api.kalender-sync.de/v1/me \
  -H "Authorization: Bearer $KS_KEY"

{
  "account_id": "…",
  "key": {
    "id": "…",
    "name": "My website",
    "mode": "test",
    "scopes": ["publisher:read", "publisher:write", "publisher:stats"],
    "calendar_ids": null
  }
}

mode: "test" means: this key only sees sandbox calendars.

3. Create a calendar

curl https://api.kalender-sync.de/v1/publisher/calendars \
  -H "Authorization: Bearer $KS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Riverside Yoga",
    "description": "Classes and workshops at the studio by the river.",
    "timezone": "America/New_York",
    "language": "en",
    "site_url": "https://example.org",
    "brand_color": "#0f766e"
  }'

The response (201 Created) contains everything you need next:

{
  "id": "cal_XXXXXXXXXXXX",
  "mode": "test",
  "name": "Riverside Yoga",
  "timezone": "America/New_York",
  "default_duration": "PT1H",
  "show_events": true,
  "subscribe_page_url": "https://app.kalender-sync.de/subscribe/cal_XXXXXXXXXXXX",
  "feed_url": "https://feeds.kalender-sync.de/f_….ics",
  "subscribe_links": { "google": "…", "outlook": "…", "office365": "…", "apple": "webcal://…" },
  "event_count": 0,
  "…": "…"
}

Keep the id:

export KS_CAL="cal_XXXXXXXXXXXX"

4. Write an event

You create events with PUT under your own id, here wp-101. The same call updates the event later.

curl -X PUT https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/events/wp-101 \
  -H "Authorization: Bearer $KS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sunset Yoga",
    "start": "2026-11-12T18:00:00",
    "end": "2026-11-12T19:15:00",
    "location": "Rooftop, 5 Main Street, New York",
    "description": "Bring a mat.",
    "url": "https://example.org/classes/sunset-yoga"
  }'

Without a timezone on the event, the calendar’s time zone applies. The response is 201 Created the first time and 200 OK on every change. Send the same event again and you get "changed": false.

A weekly series looks like this:

curl -X PUT https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/events/wp-102 \
  -H "Authorization: Bearer $KS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Morning Flow",
    "start": "2026-11-03T07:30:00",
    "end": "2026-11-03T08:30:00",
    "recurrence": { "rules": ["FREQ=WEEKLY;BYDAY=TU;COUNT=8"] }
  }'

5. Subscribe

Open the subscribe_page_url from step 3 in your browser. You see your events, the “Test calendar” note and the button with the app menu. Subscribe to the calendar in your own calendar app to try it.

For your website you only need the button:

<div class="ks-subscribe" data-calendar="cal_XXXXXXXXXXXX"></div>
<script src="https://app.kalender-sync.de/embed/v1/button.js" async></script>

→ Button and ks:subscribe

What next?

• Go live: create a live key under Settings › Developer / API (Basic and up) and repeat step 3 with it. Sandbox and live calendars are separate; sandbox calendars do not turn into live calendars. → Plans and limits
• Many events at once: Batch
• Reconcile regularly: Full sync
• Logo and banner: Images