# 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](https://app.kalender-sync.de/) 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:

```bash
export KS_KEY="ks_test_…"
```

## 2. Check the key

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

```json
{
  "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

```bash
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:

```json
{
  "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`:

```bash
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.

```bash
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:

```bash
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:

```html
<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](https://docs.kalender-sync.de/en/api/button/)

## 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](https://docs.kalender-sync.de/en/abo-kalender/tarife/)
- **Many events at once:** [Batch](https://docs.kalender-sync.de/en/api/batch/)
- **Reconcile regularly:** [Full sync](https://docs.kalender-sync.de/en/api/full-sync/)
- **Logo and banner:** [Images](https://docs.kalender-sync.de/en/api/images/)