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: belegte Veranstaltungen, Ablaufpunkte, Raumgruppen, offene Anfragen und Sperrzeiten zählen.

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=false

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.
• free_location_ids — die Räume, die im Fenster frei sind.
• conflicts — was im Weg steht. type sagt, wodurch:

• 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 offenen Anfragen. Sperrzeiten und 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.