Powered by

# 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: Sie können damit Chatbot-Antworten erzeugen und Analytics-Events aus Ihrem eigenen Frontend an die Plattform melden.

Antworten generieren
../partner-api-antworten-generieren/
Analytics-Events
../analytics-events/

# Protokoll und Endpunkt

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.

# Endpunkt-Überblick

Methode Pfad Beschreibung
POST /partner/v1/answer-generations Erzeugt eine Chatbot-Antwort auf eine Nutzer*innen-Nachricht.
POST /partner/v1/events/analytics Legt ein Analytics-Event zu einer Nutzer*innen-Interaktion an.
GET /partner/health Healthcheck. 200 mit {"status":"UP"}, 503 mit {"status":"DOWN"}.

# Authentifizierung

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.

# Token anfordern

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>'

Rufen Sie curl.exe explizit auf: In der Windows PowerShell wird ein einfaches curl zu Invoke-WebRequest aufgelöst, das diese Parameter nicht unterstützt. Das Zeilenfortsetzungszeichen ist ein Backtick, auf den kein Leerzeichen folgen darf.

 
{
  "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.

# Token verwenden

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

Header Beschreibung
Authorization Bearer <access_token> – das oben angeforderte Token.
kauz-chatbot Name des Chatbots, an den sich die Anfrage richtet (links oberhalb des Seitenmenüs im aiStudio). 
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.

# Fehlerbehandlung

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

{
  "statusCode": 401,
  "message": "Invalid token.",
  "correlationId": "kQ8sT2vB7nZ1xA",
  "errorCode": "PA_ERR_1002"
}
Feld Typ Beschreibung
statusCode number HTTP-Statuscode der Antwort.
message string Menschenlesbare Beschreibung des Fehlers.
correlationId string ID der Anfrage. Geben Sie sie an, wenn Sie ein Problem melden.
errorCode string (optional) Stabiler, maschinenlesbarer Code für bekannte Fehler – siehe Tabelle unten.

# Fehlercodes

Code Beschreibung
PA_ERR_1000 Der Chatbot hat sein monatliches Kostenlimit erreicht.
PA_ERR_1001 Der Chatbot hat sein tägliches Kostenlimit erreicht.
PA_ERR_1002 Ungültiges Token.
PA_ERR_1003 Abgelaufenes Token.

# Fehler während eines Streams

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.