API & Schlüssel

Der AI Hub kann auf mehrere Arten in bestehende Systeme integriert werden: Agents über eine REST-API für die Server-zu-Server-Kommunikation aus einer eigenen serverseitigen Anwendung, und Widgets zum Einbetten einer Chat-Komponente direkt in externe Websites oder Anwendungen. Die Inference-API stellt die Modelle des Workspaces zusätzlich über eine OpenAI-kompatible Schnittstelle bereit. Auch die Data Push API zur Datenübertragung an den AI Hub wird über API-Schlüssel gesichert.

Die vollständige API-Dokumentation mit allen Endpunkten und Parametern finden Sie in der Swagger OpenAPI Collection.

API-Schlüssel

Jeder API-Zugriff erfordert einen API-Schlüssel. Schlüssel werden im Bereich API Keys der Admin-Oberfläche erstellt und verwaltet.

Schlüssel erstellen

Beim Erstellen eines API-Schlüssels wird konfiguriert:

• Typ: Bestimmt, wofür der Schlüssel verwendet wird:

Typ	Beschreibung
Agent	Server-zu-Server-Zugriff auf einen bestimmten Agent über die Chat-API — für den Einsatz in eigenen Backends
Widget	Bettet ein bestimmtes Widget (inkl. Agent und Darstellung) in externe Websites oder Anwendungen ein
Data Push	Ermöglicht das Senden von Daten an eine bestimmte Data Push Collection
Inference	Zugriff auf die Inference-API — die OpenAI-kompatible Schnittstelle zu den Modellen des Workspaces

• Name: Ein beschreibender Name zur Identifikation des Schlüssels.
• Beschreibung (optional): Zweck oder Einsatzbereich des Schlüssels.
• Gültig bis (optional): Ablaufdatum. Nach diesem Datum funktioniert der Schlüssel nicht mehr. Ohne Angabe ist der Schlüssel unbefristet gültig.

Öffentlich vs. Geheim

Für Agent- und Widget-Schlüssel wird zusätzlich zwischen öffentlichen und geheimen Schlüsseln unterschieden:

• Öffentlich: Kann in browserseitigen Anwendungen (z. B. eingebetteten Widgets) verwendet werden. Es müssen erlaubte Domains angegeben werden — der Schlüssel funktioniert nur auf diesen Domains.
• Geheim: Darf nur in serverseitigen Anwendungen verwendet werden und sollte niemals im Browser-Code sichtbar sein.

Data-Push- und Inference-Schlüssel sind immer geheim — für sie entfällt die Auswahl. Sie sind ausschließlich für die serverseitige Verwendung vorgesehen und dürfen nicht an den Browser ausgeliefert werden.

warnung

Der API-Schlüssel wird nach dem Erstellen einmalig angezeigt und automatisch in die Zwischenablage kopiert. Speichern Sie den Schlüssel sicher — er kann danach nicht mehr eingesehen werden.

Schlüssel verwalten

Bestehende Schlüssel können nachträglich bearbeitet werden (Name, Beschreibung, erlaubte Domains). Der Schlüssel selbst kann nicht geändert oder erneut angezeigt werden.

Beim Löschen eines Schlüssels wird darauf hingewiesen, dass der Schlüssel in allen Anwendungen und Systemen ersetzt werden muss, in denen er verwendet wird.

Inference-API

Die Inference-API stellt die im Workspace verfügbaren Chat-Modelle über eine OpenAI-kompatible Schnittstelle bereit. Damit lassen sich bestehende Anwendungen und Bibliotheken, die bereits gegen die OpenAI-API entwickelt wurden, auf den AI Hub umstellen — in der Regel genügt es, Basis-URL und Schlüssel zu tauschen.

Im Unterschied zur Chat-API richtet sich die Inference-API nicht an einen konfigurierten Agent: Es gibt keinen Flow, keine Wissensquellen und keine Guardrails. Angesprochen wird direkt das Modell. Für alles, was Agent-Verhalten benötigt, ist die Chat-API mit einem Agent-Schlüssel der richtige Weg.

Authentifizierung

Die Inference-API erwartet den Schlüssel — abweichend von den übrigen Endpunkten, die den Header X-Api-Key verwenden — als Bearer-Token:

Authorization: Bearer <API-SCHLÜSSEL>

Es wird ausschließlich ein Schlüssel vom Typ Inference akzeptiert — Schlüssel anderer Typen werden abgewiesen. Der Workspace ergibt sich aus dem Schlüssel und muss nicht mitgesendet werden.

Endpunkte

Endpunkt	Beschreibung
POST /api/v1/inference/chat/completions	Erzeugt eine Antwort zu einem Nachrichtenverlauf (OpenAI-kompatibles ChatCompletion-Objekt)
GET /api/v1/inference/models	Listet die für den Schlüssel verfügbaren Chat-Modelle im OpenAI-Format auf

Das Feld model muss dem Modellnamen eines aktiven, konfigurierten Modells entsprechen — welche das sind, liefert der Endpunkt models.

Streaming

Das Verhalten steuert das Feld stream im Request-Body:

• stream: false (Standard): Die Antwort ist ein einzelnes ChatCompletion-JSON-Objekt.
• stream: true: Die Antwort ist ein text/event-stream aus ChatCompletionChunk-Events und endet mit data: [DONE].

Unterstützte Rollen

Es werden nur die Rollen system, user und assistant unterstützt. Tool- und Function-Rollen gibt es nicht — Anwendungen, die Function Calling über die OpenAI-API nutzen, lassen sich daher nicht unverändert übernehmen.

Für beide Endpunkte ist die Anzahl der Anfragen pro Zeitraum begrenzt. Bei Überschreitung antwortet die API mit 429 Too Many Requests.

Die vollständigen Request- und Response-Schemata inklusive aller optionalen Parameter (z. B. temperature, max_tokens, top_p, stop) sind in der Swagger OpenAPI Collection dokumentiert.