Verfügbarkeit über die API abfragen

Mit der Schnittstelle GET /api/v1/availability fragt dein eigenes System bei Univents nach, ob ein Zeitraum frei ist: für einen einzelnen Raum oder für alle Räume eines Workspace. Damit kann deine Website, dein Planungstool oder ein anderes System eine Zusage geben, ohne eine Buchung auszulösen.

Die Aussage ist dieselbe, die auch die Buchungsseite und der Chat verwenden: alle Veranstaltungen deines Workspace zählen (auch Entwürfe und Optionen; nur abgesagte, abgelehnte und archivierte nicht), dazu Ablaufpunkte, Raumgruppen und Sperrzeiten. Offene Anfragen halten einen Raum nicht — du kannst sie aber auf Wunsch als vorläufige Belegung mitprüfen.

Schlüssel und Berechtigung

Du brauchst einen API-Schlüssel mit der Berechtigung Locations lesen. Erstellen kannst du ihn unter Integrationen → Entwickler → API-Schlüssel — die Einrichtung steht im Artikel zu den API-Schlüsseln. Schicke ihn bei jeder Anfrage als Authorization: Bearer <Schlüssel> mit. Ein Schlüssel ohne diese Berechtigung bekommt eine Absage, kein leeres Ergebnis.

Die Anfrage

GET /api/v1/availability?from=2026-10-01&to=2026-10-03
GET /api/v1/availability?from=2026-10-01T18:00&to=2026-10-01T23:00&location_id=<Raum-ID>
GET /api/v1/availability?from=2026-10-01&to=2026-10-03&buffer_minutes=120&include_soft_holds=true

Ohne Zeitzone gelten Datum und Uhrzeit in der Zeitzone deines Workspace. Hängst du ein Z oder einen Versatz an (2026-10-01T18:00Z), gilt der Wert wörtlich.

Die Antwort

{
  "available": false,
  "window": {
    "requested_from": "2026-10-01",
    "requested_to": "2026-10-03",
    "from": "2026-09-30T22:00:00.000Z",
    "to": "2026-10-03T22:00:00.000Z",
    "buffer_minutes": 120
  },
  "free_location_ids": ["…"],
  "locationAvailable": false,
  "conflicts": [
    {
      "type": "event_overlap",
      "location_id": "…",
      "from": "2026-10-02T15:00:00.000Z",
      "to": "2026-10-02T22:00:00.000Z",
      "confirmed": true
    },
    {
      "type": "soft_hold",
      "location_id": "…",
      "from": null,
      "to": null
    }
  ],
  "notes": ["Soft holds (open, non-archived requests) are counted per day …"]
}

• available — frei oder nicht, über alle geprüften Räume. Bei einem einzelnen angefragten Raum steht zusätzlich locationAvailable.
• window — was tatsächlich geprüft wurde. Mit Puffer ist das Fenster auf beiden Seiten weiter als angefragt; requested_from/requested_to zeigen unverändert, was du geschickt hast. Gezeigt wird dabei dein buffer_minutes; die Rüstzeit eines Raums steckt nicht darin, sondern je Konflikt in effectiveBufferMinutes.
• free_location_ids — die Räume, die im Fenster frei sind.
• conflicts — was im Weg steht. type sagt, wodurch:

effectiveBufferMinutes steht an einem Belegungs-Konflikt, sobald für diesen Raum eine Rüst- und Reinigungszeit wirksam war: der Wert in Minuten, mit dem gerechnet wurde — max(buffer_minutes, Rüstzeit des Raums), höchstens 1440. Fehlt er, wurde ohne Puffer geprüft. Beim Konflikt blocked_period und bei der Anfragen-Obergrenze (capacity) steht er nicht.

• degraded — nur vorhanden, wenn ein Teil der Prüfung nicht gelesen werden konnte. Dann ist die Antwort nicht abschliessend: behandle sie nicht als Zusage, sondern frage erneut.
• notes — die Feinheiten, die man kennen muss, um die Antwort richtig zu lesen; siehe unten.

Was die Antwort nicht ist

• Keine Buchung. Der Aufruf reserviert nichts. Zwischen Abfrage und Buchung kann ein anderer Vorgang den Raum belegen — die Buchung selbst prüft erneut.
• Keine Personenangaben. Die Antwort nennt Raum-Kennungen und Zeiträume, keine Namen, keine Kontakte, keine Ansprechpartner.
• Keine Seiten-Obergrenze. Die Obergrenze paralleler Anfragen wird je Buchungsseite eingestellt; ein API-Aufruf hat keinen Seitenbezug. Deshalb steht sie in dieser Antwort nicht — fehlt sie, ist das keine Null.
• Keine Minutengenauigkeit bei Sperrzeiten und vorläufigen Anfragen. Sperrzeiten und (mit include_soft_holds=true) offene Anfragen werden tagesweise in der Zeitzone des Workspace gewertet, Veranstaltungen dagegen minutengenau. Das Ergebnis ist dadurch nie grosszügiger als die Buchungsseite, kann aber strenger sein. Die notes der Antwort sagen das im Einzelfall an.

Fehlerfälle

Ein leeres Zeitfenster oder ein Tippfehler im Datum führt nie zu „frei" — solche Anfragen werden abgewiesen. Die ausführliche Beschreibung der Schnittstelle samt aller Felder findest du in der API-Referenz unter /api/v1/docs.