Entwickler-API

Öffentliche REST-API zur vollständigen Verwaltung Ihres Belegungskalenders: Buchungen (inkl. Serien & Lebenszyklus), Standorte, Gebäude, Räume, Ressourcen, Öffnungszeiten und Konto-Verwaltung. Alle Anfragen werden mit einem tenant-spezifischen API-Schlüssel authentifiziert.

OpenAPI-Spezifikation (JSON)

Authentifizierung

Senden Sie den Schlüssel im Authorization-Header als Bearer-Token. Schlüssel verwalten Sie unter Einstellungen → API-Schlüssel.

Berechtigungen

Jeder Schlüssel trägt explizite Berechtigungen im Format resource:action. read liest, write legt an, ändert oder löscht. Vergeben Sie nur, was das Kundensystem wirklich braucht.

Buchungen

bookings:read— Buchungen lesen
bookings:write— Buchungen anlegen & verwalten

Räume & Ressourcen

rooms:read— Räume lesen
rooms:write— Räume verwalten
resources:read— Ressourcen lesen
resources:write— Ressourcen verwalten

Verfügbarkeit

availability:read— Verfügbarkeit lesen
availability:write— Öffnungszeiten & Schließtage verwalten

Konto & Team

team:read— Team lesen
team:write— Team verwalten
tenant:read— Einstellungen lesen
tenant:write— Einstellungen verwalten
billing:read— Abrechnung lesen
billing:write— Abrechnung verwalten
ai:read— KI-Konfiguration lesen
ai:write— KI-Konfiguration verwalten
apikeys:read— API-Schlüssel lesen

Gefährliche Berechtigungen

apikeys:write— API-Schlüssel erzeugen & widerrufen
gdpr:read— Audit-Log & Datenexport
gdpr:write— Personen löschen & Träger entfernen

Rate-Limit

Pro Schlüssel gilt ein Limit pro Minute. Bei Überschreitung antwortet die API mit HTTP 429.

Schreibanfragen

POST/PATCH/PUT/DELETE benötigen den Header Content-Type: application/json — auch Aktions-Endpunkte ohne eigene Nutzdaten (z. B. der approve- oder cancel-Endpunkt einer Buchung) erwarten einen leeren JSON-Body.

Schnellstart

GET /api/v1/availability

Liefert belegte Zeiträume (ausstehend + freigegeben, inkl. Auf-/Abbau) im angefragten Fenster — optional auf Raum, Gebäude oder Standort eingrenzbar.

curl -H "Authorization: Bearer civical_sk_…" \
  "https://your-instance/api/v1/availability?from=2026-07-01T00:00:00Z&to=2026-07-08T00:00:00Z"

# Auf ein Gebäude oder einen Standort eingrenzen:
curl -H "Authorization: Bearer civical_sk_…" \
  "https://your-instance/api/v1/availability?buildingId=<uuid>&from=…&to=…"

GET /api/v1/campuses

Liest die Standort-/Gebäude-Hierarchie zum Navigieren der Räume. /campuses liefert Standorte inkl. Gebäude, /buildings die Gebäude (optional je Standort).

curl -H "Authorization: Bearer civical_sk_…" \
  "https://your-instance/api/v1/campuses"   # Standorte inkl. Gebäude
curl -H "Authorization: Bearer civical_sk_…" \
  "https://your-instance/api/v1/buildings"  # Gebäude (optional ?campusId=)

POST /api/v1/bookings

Legt eine ausstehende Buchungsanfrage an — für einen Einzelraum oder, mit level=BUILDING/CAMPUS und targetId, für ein ganzes Gebäude bzw. einen Standort (Konflikte fächern auf alle Räume auf). Die Verwaltung gibt sie anschließend frei.

# Einzelnen Raum buchen:
curl -X POST -H "Authorization: Bearer civical_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Probe",
    "roomId": "<uuid>",
    "start": "2026-07-03T18:00:00Z",
    "end": "2026-07-03T20:00:00Z",
    "requesterName": "Max Mustermann",
    "requesterEmail": "max@example.com"
  }' \
  "https://your-instance/api/v1/bookings"

# Ganzes Gebäude buchen (Konflikte fächern auf alle Räume auf):
#   "level": "BUILDING", "targetId": "<gebaeude-uuid>"  (statt roomId)

Vollständige Referenz

Die maschinenlesbare OpenAPI-Spezifikation listet alle Endpunkte, Parameter und Schemas — Buchungen, Standorte/Gebäude, Räume, Ressourcen, Öffnungszeiten/Schließtage, Team, Einstellungen, Abrechnung, KI, API-Schlüssel und DSGVO.