calovo JSON API v2

Schnellstart

Das Token gehört in den HTTP-Header, niemals in URL, Query-Parameter, Browser-Code oder Logs.

curl --request GET \
  --url 'https://calovo.de/api/v2/calendar-feeds?limit=20' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer calovo_v2.ACCOUNT.SECRET'

Endpunkte

Filter und Seitennavigation

• page: Seite ab 1; Standardwert 1.
• limit: 1 bis 100 Ergebnisse pro Seite; Standardwert 50.
• date_from und date_to: inklusive Zeitraumgrenzen im Format YYYY-MM-DD für Termine.
• Ohne Zeitraum werden Termine ab heute bis 18 Monate in die Zukunft geliefert; maximal sind 731 Tage pro Abfrage erlaubt.
• Erzeugt ein wiederkehrender Spezialkalender in diesem Fenster mehr als 1.200 Vorkommen, antwortet die API mit 422 result_window_too_large; der Zeitraum ist dann zu verkleinern.
• Nicht dokumentierte Query-Parameter werden mit 422 invalid_parameter abgelehnt, damit Tippfehler nicht unbemerkt auf Standardwerte zurückfallen.

Listen enthalten meta.pagination sowie navigierbare Links für self, first, last, prev und next.

Antwortformat

{
  "data": [],
  "meta": {
    "api_version": "2.0",
    "generated_at": "2026-07-17T12:00:00+00:00",
    "request_id": "67d7d160-43ca-47ce-ac31-69bce158c62e",
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total": 0,
      "last_page": 1
    }
  },
  "links": { "self": "https://calovo.de/api/v2/calendar-feeds?page=1&limit=50" }
}

Fehler werden konsistent als {"errors":[...]} mit HTTP-Status, stabilem Fehlercode und Beschreibung ausgegeben.

Bei Kalendern und Terminen enthält description Klartext. html_description kann redaktionelles HTML enthalten und muss vor einer Ausgabe im Browser nach den Regeln des Zielsystems bereinigt oder über eine Positivliste gefiltert werden.

Abgesagte Termine bleiben mit status: "cancelled" in der Antwort, damit Zielsysteme bestehende Einträge zuverlässig aktualisieren können. Reguläre Termine besitzen status: "confirmed".

Bei Ganztagsterminen markieren starts_at und ends_at den Anfang und das inklusive Ende der lokalen Kalendertage in Europe/Berlin, jeweils als UTC-Zeitstempel ausgegeben.

Betrieb und Synchronisation

• Das Standardlimit beträgt 120 Requests pro Minute und Token; da ein Account genau ein aktives Token besitzt, entspricht das dem Account-Limit. Zusätzlich schützt ein höheres IP-Abuse-Limit die Authentifizierung.
• Erfolgreiche GET-Antworten besitzen ein ETag. Mit If-None-Match erhalten Clients bei unveränderten Daten 304 Not Modified.
• X-Request-ID und meta.request_id enthalten dieselbe Korrelations-ID. Bei Supportfällen bitte diese ID mitsenden.
• Clients dürfen eine eigene, maximal 100 Zeichen lange X-Request-ID aus Buchstaben, Ziffern sowie ._:- mitsenden; sichere Werte werden unverändert zurückgegeben.
• Antworten sind als private markiert. Tokens und Antworten dürfen nicht in öffentlichen oder gemeinsam genutzten Caches landen.
• Eine Synchronisation sollte jede Seite vollständig als Snapshot abgleichen. Fehlt ein zuvor bekannter Termin dauerhaft, ist er im Zielsystem zu entfernen.
• Bei 429 gilt der Header Retry-After; bei 5xx exponentiell mit Zufallsanteil wiederholen.

Versionierung und Legacy-v1

Bestehende produktive v1-Integrationen unter /json/{id|key} bleiben kompatibel und getrennt freigeschaltet. Neue Kundenintegrationen sollen v2 verwenden. Eine spätere inkompatible Änderung erhält einen neuen Versionspfad; additive Felder können innerhalb von v2 ergänzt werden.

Legacy-Unterlagen: Swagger v1 und PDF-Kurzdokumentation v1.