Business GPT API
Auf dieser Seite finden Sie die vollständige Referenz der BusinessGPT REST-API mit allen verfügbaren Endpunkten sowie deren Parametern, Anfrage- und Antwortschemata. Sie können die Endpunkte aufklappen, um Details wie benötigte Felder, Datentypen und Beispielantworten einzusehen.
Wie Sie den technischen API-Zugang einrichten und ein Zugriffstoken erhalten, beschreiben die folgenden Anleitungen:
Berechtigungen der API-Rolle
Der technische API-Zugang ("api-User") erhält die Rolle api. Diese Rolle ist
bewusst auf die programmatische Nutzung zugeschnitten und von den Rechten
menschlicher Nutzer (user / admin) abgegrenzt. Die folgende Übersicht zeigt,
welche Funktionsbereiche der API-Rolle grundsätzlich zur Verfügung stehen:
| Funktionsbereich | Zugriff der API-Rolle |
|---|---|
| Chats / Unterhaltungen (Threads und Nachrichten) | Vollzugriff (erstellen, lesen, aktualisieren, löschen) |
| Dokumente | Vollzugriff (lesen, hochladen, aktualisieren, löschen). Bei deaktivierter Funktion Bereiche in allen Containern; bei aktivierter Funktion Bereiche nur in Containern, die keinem Bereich zugewiesen sind (siehe unten) |
| Dokumenten-Container | Nur lesen |
| Assistenten | Nur lesen |
| Bereiche (Bereichsverwaltung) | Vollzugriff (erstellen, lesen, aktualisieren, löschen) — nur wenn die Funktion Bereiche aktiviert ist (siehe unten) |
| Rechtliche Hinweise / Nutzungsbedingungen | Nur lesen |
| Administration (Konfiguration, Gruppen, Funktionen, Verbrauch) | Kein Zugriff |
| Persönliche und unternehmensweite Prompt-Bibliothek | Kein Zugriff |
| Private und persönliche Container | Kein Zugriff |
Effektiver Zugriff hängt von weiteren Faktoren ab
Die Tabelle beschreibt die rollenbasierten Grundrechte der API-Rolle. Der tatsächlich mögliche Zugriff auf einzelne Ressourcen (z. B. bestimmte Dokumenten-Container) wird zusätzlich über Gruppenzugehörigkeiten sowie die Konfiguration Ihrer BusinessGPT-Instanz gesteuert. Maßgeblich ist immer die serverseitige Autorisierung: Endpunkte, für die keine Berechtigung vorliegt, werden mit dem Statuscode 403 Forbidden beantwortet.
Wann die API-Rolle gruppenbasierten Zugriff benötigt
Die API-Rolle kann in zwei Modi arbeiten, für die unterschiedliche Zugriffsregeln gelten:
- Konsumierender Zugriff (Nutzung / „Usage") – etwa das Chatten gegen einen Dokumenten-Container oder Assistenten und das dabei stattfindende Abrufen von Wissen. Dieser Zugriff ist gruppenbasiert: Ressourcen, die auf bestimmte Gruppen beschränkt sind, stehen der API-Rolle nur zur Verfügung, wenn der api-User Mitglied einer passenden Gruppe ist. Container und Assistenten ohne Gruppenbeschränkung sind hingegen für alle zugänglich. Nur hierfür müssen Sie dem technischen Zugang gezielt die passenden Gruppen zuordnen.
- Administrativer Zugriff (Verwaltung) – das Anlegen und Pflegen von Bereichen sowie das Verwalten von Dokumenten in Containern ohne Bereichszuordnung. Dieser Zugriff ist nicht gruppenbasiert, sondern folgt dem Administrator-Modell: Die Bereichsverwaltung ist mandantenweit, die Dokumentenverwaltung ist auf Container begrenzt, die keinem Bereich zugewiesen sind (Standard- bzw. Default-Bereich). Für diese Aufgaben benötigt der api-User keine Gruppenmitgliedschaft.
Seine Gruppenzugehörigkeiten bezieht der api-User – wie menschliche Nutzer –
aus dem Zugriffstoken (groups-Claim).
Die API-Rolle und die Funktion Bereiche
Ist die Funktion Bereiche in Ihrer Instanz
aktiviert, verhält sich die API-Rolle bewusst wie ein Administrator (admin):
Sie kann die Bereichsstruktur über die API verwalten, ist bei der Verwaltung
von Inhalten aber auf Inhalte beschränkt, die keinem Bereich zugewiesen
sind. So lässt sich die Bereichsverwaltung durch angebundene Systeme
automatisieren, ohne die Isolation der einzelnen Bereiche zu durchbrechen.
| Aspekt | Verhalten der API-Rolle |
|---|---|
| Bereiche verwalten (anlegen, lesen, aktualisieren, löschen) | Möglich – gleichwertig zum Administrator. Diese Rechte sind an die aktivierte Funktion Bereiche gebunden. |
| Dokumente in Containern ohne Bereichszuordnung verwalten | Möglich (erstellen, lesen, aktualisieren, löschen). Betroffen sind ausschließlich Container, die keinem Bereich zugewiesen sind (der sogenannte Standard- bzw. Default-Bereich). |
| Dokumente in einem Bereich (zugewiesene Container) verwalten | Kein Zugriff – Inhalte innerhalb von Bereichen liegen ausschließlich bei den zuständigen Bereichsadministratoren. |
| Gruppenzuordnung für die Bereichsverwaltung | Nicht erforderlich. Der Zugriff auf die Bereichsstruktur ist – wie beim Administrator – mandantenweit und unabhängig von den Gruppen des api-Users; er sieht und verwaltet alle Bereiche, auch ohne Gruppenmitgliedschaft. |
Rolle area_admin |
Für die API-Rolle nicht anwendbar. Die API-Rolle agiert nicht als Bereichsadministrator, sondern spiegelt das Administrator-Modell wider. |
Abhängigkeit von der Funktion Bereiche
Die Rechte zur Bereichsverwaltung stehen der API-Rolle nur zur Verfügung, wenn die Funktion Bereiche aktiviert ist — analog zum Administrator. Ist die Funktion deaktiviert, existieren keine Bereiche; die API-Rolle verwaltet dann Dokumente uneingeschränkt über alle Container hinweg (es gibt keine Bereichs-Isolation). Bei aktivierter Funktion bleibt die Dokumentenverwaltung der API-Rolle auf nicht zugewiesene Container begrenzt.