# Partner-API

Die Partner-API ist der aktuelle, empfohlene Weg, um eigene Anwendungen an die Kauz-Plattform anzubinden. Sie bietet ongeboardeten Partner*innen einen kuratierten, authentifizierten Zugang zu den Kauz-Diensten für drei Anwendungsfälle:

• Chatbot-Nutzung – Sie implementieren ein eigenes Chat-Frontend: Chatbot-Antworten erzeugen und Nutzer*innen-Interaktionen als Analytics-Events an die Plattform melden.
• Datenimport – Sie pflegen die Wissensbasis (Korpora, Dokumente, Chunks) programmatisch, z. B. um eigene Import-Pipelines an die Kauz-Plattform anzubinden.
• Analytics – Sie werten die Konversationen Ihres Chatbots aus: Konversationen suchen und alle Events einer Konversation abrufen, z. B. für eigene Auswertungs- oder BI-Systeme.

Authentifizierung, Fehlerbehandlung und das grundlegende Protokoll (auf dieser Seite beschrieben) gelten für alle Anwendungsfälle gleichermaßen.

Die Partner-API bezieht sich auf Chatbots, die Sie im aiStudio angelegt haben (nicht auf den aiWorkplace). Sie richtet sich an Kund*innen und Partner*innen, die einen solchen Chatbot in eine eigene Software-Umgebung integrieren möchten, statt (oder zusätzlich zu) das von Kauz bereitgestellte Chatfenster einzubinden. Typische Beispiele:

• Eigenes Chat-Frontend statt Standard-Chatfenster: Sie bauen die Chat-Oberfläche selbst, zum Beispiel als Teil einer bestehenden App oder eines Kundenportals, und lassen im Hintergrund über /partner/v1/answer-generations die Antworten von Ihrem Kauz-Chatbot erzeugen. Über /partner/v1/events/analytics melden Sie Nutzer*innen-Interaktionen (z. B. Klicks, Bewertungen) an die Plattform, damit sie im aiStudio-Analytics-Dashboard erscheinen.
• Automatisierte Pflege der Wissensbasis: Ändern sich Ihre Inhalte häufig, zum Beispiel Produktdaten in einem PIM-System oder Artikel in einem CMS, können Sie die Datenimport-Endpunkte nutzen, um Korpora, Dokumente und Chunks per Skript oder eigener Import-Pipeline aktuell zu halten, statt sie manuell im aiStudio hochzuladen.

Für den Zugriff auf externe Dienste aus einem Chatbot heraus (z. B. ein Ticketsystem oder CRM anbinden) nutzen Sie dagegen die Custom-API-Tools im aiStudio; die Partner-API ist der umgekehrte Weg, also der Zugriff auf Ihren Chatbot von außen.

Die Partner-API steht aus Sicherheitsgründen ausschließlich verschlüsselt zur Verfügung (HTTPS). Nutzen Sie für alle Anfragen https:// als Protokoll.

Der Endpunkt ist abhängig von Ihrer Umgebung. Nachfolgend wird für die Beispiele https://example.kauz.ai als Endpunkt angenommen. Tauschen Sie die Domain durch Ihre persönliche aus, um Anfragen an Ihre Umgebung zu senden. Die fachlichen Endpunkte sind jeweils unter dem Pfad /partner/v1 verfügbar.

Eine interaktive Fassung der Schnittstellenbeschreibung finden Sie in Ihrer Umgebung unter /partner/api/docs.

Chatbot-Nutzung

Datenimport

Analytics

Alle Anwendungsfälle

Die Authentifizierung erfolgt über OAuth 2.0 mit dem Client-Credentials-Grant. Sie fordern zunächst ein Token an und senden dieses anschließend als Bearer-Credential an jede Anfrage.

client_id und client_secret verwalten Sie selbst im aiStudio unter Partner-API-Zugriff . Dort wird die client_id dauerhaft angezeigt; das client_secret wird auf Kauz-Seite erzeugt und nur einmal sichtbar – bewahren Sie es direkt sicher auf. Über dieselbe Seite können Sie das Secret erneuern und den Zugang entziehen.

Ersetzen Sie {realm} durch Ihre client_id.

curl -X POST \
  'https://example.kauz.ai/auth/realms/{realm}/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<your_client_id>' \
  -d 'client_secret=<your_client_secret>'

curl.exe -X POST `
  'https://example.kauz.ai/auth/realms/{realm}/protocol/openid-connect/token' `
  -H 'Content-Type: application/x-www-form-urlencoded' `
  -d 'grant_type=client_credentials' `
  -d 'client_id=<your_client_id>' `
  -d 'client_secret=<your_client_secret>'

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 900
}

Tokens sind an ihren Realm gebunden und 15 Minuten gültig. Werten Sie expires_in (Sekunden) aus und fordern Sie rechtzeitig ein neues Token an.

Jede Anfrage an einen fachlichen Endpunkt benötigt zwei Header:

curl --location --request POST "https://example.kauz.ai/partner/v1/answer-generations" \
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
--header "kauz-chatbot: helpdesk" \
--header "Content-Type: application/json" \
[...]

Um die Endpunkte direkt auf der Seite /partner/api/docs auszuprobieren, klicken Sie dort auf Authorize und fügen das access_token ein.

Jeder Fehler wird als JSON-Objekt der folgenden Struktur zurückgegeben:

{
  "statusCode": 401,
  "message": "Invalid token.",
  "correlationId": "kQ8sT2vB7nZ1xA",
  "errorCode": "PA_ERR_1002"
}

Beim Streaming von Antworten (text/event-stream) werden die Antwort-Header gesendet, bevor die Antwort vollständig ist. Ein Fehler, der nach dem Beginn des Streamings auftritt, kann den HTTP-Statuscode deshalb nicht mehr verändern. Ein solcher Fehler wird als letztes Event mit dem Namen app-error gesendet, dessen data-Payload der oben beschriebene JSON-Fehlerkörper ist. Anschließend wird der Stream geschlossen:

event: app-error
data: {"statusCode":401,"message":"Invalid token.","correlationId":"kQ8sT2vB7nZ1xA","errorCode":"PA_ERR_1002"}

Tritt der Fehler auf, bevor das erste Event gesendet wurde, erhalten Sie eine reguläre JSON-Fehlerantwort mit dem entsprechenden HTTP-Statuscode.