# Full sync

If your plugin was inactive for a while or a request got lost, a **full sync** brings the calendar back in line with your system. Recommended: on first connection and then once a day, for example by WP-Cron.

## Steps

**1. Start a sync**

```bash
curl -X POST https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/syncs \
  -H "Authorization: Bearer $KS_KEY"
```

```json
{ "sync_id": "sync_XXXXXXXXXXXXXXXX", "expires_at": "2026-11-03T15:02:11.000Z" }
```

A sync is valid for **one hour**.

**2. Send every current event**

Send every event that exists in your system by [batch](https://docs.kalender-sync.de/en/api/batch/) with the `sync_id`:

```bash
curl https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/events/batch \
  -H "Authorization: Bearer $KS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_id": "sync_XXXXXXXXXXXXXXXX",
    "operations": [
      { "method": "PUT", "external_id": "wp-1482", "event": { "title": "Sunset Yoga", "start": "2026-11-12T18:00:00" } },
      { "method": "PUT", "external_id": "wp-1490", "event": { "title": "Yin Yoga", "start": "2026-11-13T18:30:00" } }
    ]
  }'
```

Unchanged events cost nothing here: they are only marked as confirmed, not rewritten. The `sync_id` only exists on batch, not on the single PUT.

**3. Complete the sync**

```bash
curl -X POST https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/syncs/sync_XXXXXXXXXXXXXXXX/complete \
  -H "Authorization: Bearer $KS_KEY"
```

```json
{ "sync_id": "sync_XXXXXXXXXXXXXXXX", "deleted": 3, "remaining": 42 }
```

This deletes every event that was **not** sent during the sync. Events you wrote outside the sync while it was running (for example a normal save on the website) are kept.

## Protection against emptying a calendar

If completing would delete **more than half** of the events, the API refuses with `409` [`large_delete`](https://docs.kalender-sync.de/en/api/errors/large_delete/). A half-finished export should never empty a calendar with thousands of subscribers.

If the deletion is intended, confirm it:

```bash
curl -X POST https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/syncs/sync_XXXXXXXXXXXXXXXX/complete \
  -H "Authorization: Bearer $KS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "confirm_large_delete": true }'
```

## Errors

| Code | When |
|---|---|
| [`sync_not_found`](https://docs.kalender-sync.de/en/api/errors/sync_not_found/) | The `sync_id` does not belong to this calendar. |
| [`sync_expired`](https://docs.kalender-sync.de/en/api/errors/sync_expired/) | The hour is over. Start a new sync. |
| [`sync_completed`](https://docs.kalender-sync.de/en/api/errors/sync_completed/) | The sync was already completed. |
| [`large_delete`](https://docs.kalender-sync.de/en/api/errors/large_delete/) | More than half would be deleted. |