REST-API

Mit der API kannst du Kalender und Termine aus anderen Programmen lesen und schreiben, etwa aus einer Warenwirtschaft, einem Ticketsystem oder einer eigenen App.

• Authentifizierung
• Grundlagen
• Kalender
• Termine
• Serientermine
• Anhänge
• Export
• Fehler

Authentifizierung

Der Administrator deiner Firma legt unter Verwaltung → API-Schlüssel einen Schlüssel an. Dort legt er auch fest, was der Schlüssel darf: Rechte und Kalender, genau wie bei Personen. Der Schlüssel wird nur einmal angezeigt. Er wird bei jeder Anfrage als Bearer-Token mitgeschickt:

curl https://api.rstcal.com/v1/calendars \
  -H "Authorization: Bearer kal_1a2b3c4d_…"

Schlüssel mit der Option „Verwaltung“ dürfen zusätzlich Kalender anlegen, ändern und löschen. Personen und API-Schlüssel lassen sich über die API nicht verwalten.

Grundlagen

• Basis-URL: https://api.rstcal.com/v1, alle Daten als JSON (Content-Type: application/json).
• Zeitpunkte nach ISO 8601. Termine mit Uhrzeit werden in UTC zurückgegeben (2026-11-10T08:00:00Z). Beim Schreiben ist jede Zeitzonen-Angabe erlaubt (2026-11-10T09:00:00+01:00).
• Ganztägige Termine: "all_day": true, start/end als Datum YYYY-MM-DD; end ist exklusiv (ein Tag: start=2026-11-10, end=2026-11-11).
• Ratenbegrenzung: 600 Anfragen pro Minute und Schlüssel (danach HTTP 429).

Kalender

[
  { "id": 12, "name": "Anna", "color": "#c62828", "sort_order": 0, "active": true, "editable": true },
  { "id": 13, "name": "Ben",  "color": "#1565c0", "sort_order": 1, "active": true, "editable": false }
]

Termine

Termin anlegen

curl -X POST https://api.rstcal.com/v1/events \
  -H "Authorization: Bearer kal_…" -H "Content-Type: application/json" \
  -d '{
    "title": "Glasfaser-Anschluss Müller",
    "calendar_ids": [12, 13],
    "start": "2026-11-10T09:00:00+01:00",
    "end":   "2026-11-10T11:30:00+01:00",
    "location": "Hauptstr. 5, 79774 Albbruck",
    "description": "Kunde ist ab 9 Uhr da."
  }'

Antwort / Termin-Objekt

{
  "id": "481",
  "calendar_id": 12,
  "calendar_ids": [12, 13],
  "title": "Glasfaser-Anschluss Müller",
  "location": "Hauptstr. 5, 79774 Albbruck",
  "description": "Kunde ist ab 9 Uhr da.",
  "all_day": false,
  "start": "2026-11-10T08:00:00Z",
  "end": "2026-11-10T10:30:00Z",
  "rrule": null,
  "series_id": null,
  "recurrence_key": null,
  "created_by_name": "API: Warenwirtschaft",
  "attachments": []
}

Ein Termin kann mehreren Kalendern zugeordnet sein (calendar_ids). Ändern darf ihn nur, wer alle zugeordneten Kalender bearbeiten darf.

Serientermine

Beim Anlegen oder Ändern setzt man rrule als RFC-5545-Regel ohne „RRULE:“. Erlaubt sind FREQ (DAILY, WEEKLY, MONTHLY, YEARLY), INTERVAL, BYDAY, BYMONTHDAY, BYMONTH, BYSETPOS, COUNT (max. 1000) und UNTIL.

{ "title": "Teammeeting", "calendar_ids": [12], "start": "2026-11-02T08:00:00+01:00",
  "end": "2026-11-02T08:30:00+01:00", "rrule": "FREQ=WEEKLY;BYDAY=MO,TH" }

• Die Uhrzeit gilt in der Zeitzone der Firma und bleibt über die Sommer- und Winterzeit gleich.
• Einzelne Vorkommen haben die ID {serie}:{datum}, z. B. 482:2026-11-05.
• Beim Ändern, Verschieben und Löschen eines Vorkommens gibt scope an, was betroffen ist: one (nur dieser, Standard), following (dieser und folgende) oder all (ganze Serie). Bei PUT/PATCH steht scope im JSON, bei DELETE als ?scope=.
• Einzeln geänderte Vorkommen haben eine eigene numerische ID und verweisen per series_id auf die Serie.

Anhänge

curl -X POST https://api.rstcal.com/v1/events/481/attachments \
  -H "Authorization: Bearer kal_…" -F "files=@plan.pdf"

Export

Fehler

Fehler kommen mit passendem HTTP-Status und einem Fehlercode zurück:

HTTP/1.1 403 Forbidden
{ "error": "err.no_permission_calendar" }