Anleitungen API

Runs über die API starten und Ergebnisse abrufen

Ihre Skripte und CI-Pipelines starten Testläufe und lesen die Ergebnisse direkt aus gentesty, inklusive Bewertungen pro Evaluator und vollständigem Transkript.

Für
Entwickler und gentesty-Administratoren
Zeitbedarf
Rund 15 Minuten
Abo
Enterprise

Überblick

Mit der gentesty API v1 starten Sie Runs und lesen deren Ergebnisse, ohne das Dashboard zu öffnen. Die API kann:

  • Bots, Testfälle und Tags auflisten
  • Runs starten, für einzelne Testfälle, ganze Bots oder alle Testfälle eines Tags
  • Run-Gruppen und Runs abfragen, mit den Bewertungen pro Evaluator und dem vollständigen Transkript

Alle Pfade beginnen mit /v1 und liegen auf dem Backend Ihres Workspaces. Ist Ihr Dashboard unter https://acme.gentesty.com erreichbar, lautet die Basis-URL https://acme-backend.gentesty.com. Die vollständige OpenAPI-Beschreibung liegt ohne Anmeldung unter /v1/openapi.yaml.

Bevor Sie beginnen

  • Ihr gentesty-Workspace nutzt das Enterprise-Abo.
  • Sie haben in gentesty die Rolle Eigentümer oder Workspace Administrator. Nur diese Rollen dürfen API-Clients anlegen, ersetzen und löschen.
  • Sie haben einen HTTP-Client. Die Beispiele nutzen curl und jq.

01 API-Client anlegen

gentesty Account › User Management › API

Ein API-Client ist der Zugang für ein Skript oder eine Pipeline. Legen Sie pro Anwendung einen eigenen an, dann können Sie einen einzelnen Zugang sperren.

  1. Klicken Sie auf API-Client anlegen.

  2. Geben Sie einen Name ein, zum Beispiel CI-Pipeline (höchstens 64 Zeichen).

  3. Wählen Sie die Berechtigungsstufe:

    BerechtigungsstufeErlaubt
    Ergebnisse lesenBots, Testfälle, Tags, Runs und Ergebnisse lesen.
    Runs starten und Ergebnisse lesenAlles aus Ergebnisse lesen und zusätzlich Runs starten.
  4. Klicken Sie auf Anlegen. Der Dialog zeigt Client ID, Client Secret, Token-URL und ein fertiges Beispiel.

  5. Kopieren Sie das Client Secret in Ihren Secret-Speicher, zum Beispiel in die geschützten Variablen Ihrer CI-Pipeline.

  6. Schließen Sie den Dialog mit Ich habe das Secret gespeichert.

Die Berechtigungsstufe lässt sich später nicht ändern. Für eine andere Stufe legen Sie einen neuen Client an und löschen den alten. Ein Workspace kann bis zu 25 API-Clients haben.

02 Access Token anfordern

Jeder Aufruf braucht ein Access Token. Sie erhalten es mit Client ID und Client Secret von der Token-URL, über den OAuth-2.0-Flow Client Credentials.

export TOKEN_URL="<Token-URL aus dem Dialog>"
export CLIENT_ID="<Client ID>"
export CLIENT_SECRET="<Client Secret>"
export BASE_URL="https://<workspace>-backend.gentesty.com"

TOKEN=$(curl -s -X POST "$TOKEN_URL" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" | jq -r .access_token)

Ein Token gilt 5 Minuten. Danach antwortet die API mit 401. Fordern Sie dann ein neues Token an, einen Refresh-Token gibt es nicht.

03 API aufrufen

Senden Sie das Token in jedem Aufruf im Header Authorization:

curl -H "Authorization: Bearer $TOKEN" "$BASE_URL/v1/bots"

Die Antwort listet alle Chat- und Voicebots Ihres Workspaces mit id, name und type. Tokens von API-Clients gelten nur für die Pfade unter /v1.

04 Runs starten und Ergebnisse lesen

Ein typisches Skript für eine CI-Pipeline hat vier Schritte. Es braucht einen Client mit der Stufe Runs starten und Ergebnisse lesen und die Variablen aus Schritt 2.

Diese Hilfsfunktionen holen für jeden Aufruf ein frisches Token. So läuft das Skript auch weiter, wenn das Warten länger als 5 Minuten dauert.

token() {
  curl -s -X POST "$TOKEN_URL" -d grant_type=client_credentials \
    -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET" | jq -r .access_token
}
api() { curl -s -H "Authorization: Bearer $(token)" "$@"; }
  1. IDs der Bots und Tags nachschlagen:

    api "$BASE_URL/v1/bots" | jq '.items[] | {id, name, type}'
    api "$BASE_URL/v1/tags" | jq '.items[] | {id, name}'
  2. Runs starten, hier alle Testfälle eines Tags. Statt tag_ids gehen auch bot_ids (alle Testfälle eines Bots) und case_ids (einzelne Testfälle), auch kombiniert. bot_type ist Pflicht: chatbot oder voicebot.

    START=$(api -X POST "$BASE_URL/v1/runs" \
      -H "Content-Type: application/json" \
      -d '{"bot_type":"chatbot","tag_ids":["<tag-id>"]}')
    GROUP_ID=$(echo "$START" | jq -r .run_group_id)
    [ "$GROUP_ID" != null ] || { echo "$START"; exit 1; }

    Die Antwort 202 enthält run_group_id und die run_ids der gestarteten Runs. Schlägt der Start fehl, gibt die letzte Zeile die Fehlermeldung aus und bricht ab.

  3. Warten, bis die Run-Gruppe fertig ist:

    STATUS=running
    until [ "$STATUS" = passed ] || [ "$STATUS" = failed ]; do
      sleep 15
      STATUS=$(api "$BASE_URL/v1/run-groups/$GROUP_ID" | jq -r .status)
    done
  4. Ergebnisse lesen, mit den nicht bestandenen Evaluatoren pro Testfall:

    api "$BASE_URL/v1/run-groups/$GROUP_ID/runs?size=50" | jq '.items[] | {case_name, status,
      failed: [.evaluations[] | select(.passed | not) | .evaluator_name]}'

    Hat die Gruppe mehr als 50 Runs, lesen Sie mit &page=2 usw. weiter, bis page * size >= total.

Das Transkript und die Detailvergleiche eines Runs liefert api "$BASE_URL/v1/runs/<run-id>". Beenden Sie das Skript in der Pipeline mit [ "$STATUS" = passed ], dann schlägt der Job bei fehlgeschlagenen Testfällen fehl.

API-Runs zählen wie Runs aus dem Dashboard zum Verbrauch Ihres Abos und erscheinen dort mit dem Auslöser API.

Endpunkte

MethodePfadLiefertStufe
GET/v1/botsAlle Chat- und Voicebots, nach Name sortiertErgebnisse lesen
GET/v1/casesTestfälle, seitenweise. Filter bot_id und tag_idErgebnisse lesen
GET/v1/tagsAlle Tags, nach Name sortiertErgebnisse lesen
POST/v1/runsStartet einen Run pro ausgewähltem TestfallRuns starten
GET/v1/runs/{id}Ein Run mit Bewertungen, Detailvergleichen und TranskriptErgebnisse lesen
GET/v1/run-groupsRun-Gruppen, neueste zuerst, seitenweiseErgebnisse lesen
GET/v1/run-groups/{id}Eine Run-Gruppe mit Status und Anzahl Runs pro StatusErgebnisse lesen
GET/v1/run-groups/{id}/runsDie Runs einer Gruppe mit Bewertungen und Transkripten, seitenweiseErgebnisse lesen
GET/v1/openapi.yamlDie OpenAPI-Beschreibungohne Token
  • Seiten: page beginnt bei 1, size ist standardmäßig 20 und höchstens 100, bei /v1/run-groups/{id}/runs höchstens 50. Die Antwort enthält items, page, size und total.
  • Status einer Run-Gruppe: running, bis alle Runs fertig sind. Danach failed, wenn ein Run fehlgeschlagen oder mit einem Fehler beendet ist, sonst passed.
  • Status eines Runs: new und invoked (wartet), running, success (mindestens ein Evaluator hat alle erwarteten Ausgaben bestätigt), failed (kein Evaluator hat das), error (Run konnte nicht abgeschlossen werden).
  • Detailvergleiche: Wie jede Bot-Nachricht mit jeder erwarteten Antwort verglichen wurde (matches), liefert nur /v1/runs/{id}. In /v1/run-groups/{id}/runs fehlt das Feld, damit die Seiten klein bleiben.

Limits

  • Jeder API-Client darf 5 Anfragen pro Sekunde senden, kurzzeitig bis zu 20 am Stück.
  • Ein Start umfasst höchstens 100 Bots, 1.000 Testfälle und 100 Tags.
  • Ein Workspace verarbeitet über die API einen Start nach dem anderen. Ein zweiter Start in derselben Zeit erhält 429.
  • Wer das Limit überschreitet, erhält 429 mit dem Header Retry-After. Warten Sie so viele Sekunden und wiederholen Sie den Aufruf.

API-Clients verwalten

gentesty Account › User Management › API

  • Secret ersetzen erzeugt ein neues Client Secret und zeigt es einmal an. Das alte Secret funktioniert ab sofort nicht mehr. Passen Sie alle Skripte an, die es verwenden.
  • API-Client löschen entfernt den Zugang endgültig.
  • Bereits ausgegebene Tokens bleiben nach beidem bis zu ihrem Ablauf gültig, also höchstens 5 Minuten.
  • Wechselt Ihr Workspace vom Enterprise-Abo in ein anderes, bleiben die Clients bestehen, aber jeder Aufruf erhält 403.

Wählen Sie Ergebnisse lesen, wenn ein Skript nur auswertet. Legen Sie das Client Secret nur in einem Secret-Speicher ab, nie im Code-Repository oder in Logs. Ersetzen Sie es, wenn jemand mit Zugriff Ihr Team verlässt.

Fehlerbehebung

Fehler kommen als JSON, message nennt den Grund:

{ "status": "FAILED", "httpCode": 403, "message": "forbidden" }
Was Sie sehenUrsacheLösung
400 mit unknown fieldDer Body enthält ein Feld, das die API nicht kennt.Nur bot_type, bot_ids, case_ids und tag_ids senden.
400 mit Select at least one bot, case or tagKeine Auswahl im Body.Mindestens eine ID in bot_ids, case_ids oder tag_ids angeben.
401 authorization failedDas Token fehlt, ist abgelaufen oder ungültig.Neues Token anfordern, siehe Schritt 2.
402Das monatliche Kontingent oder Budget Ihres Abos erlaubt keine weiteren Runs.Verbrauch und Budget unter Billing prüfen.
403 forbidden beim Start von RunsDer Client hat die Stufe Ergebnisse lesen.Client mit der Stufe Runs starten und Ergebnisse lesen verwenden.
403 forbidden auf einem Pfad unter /apiTokens von API-Clients gelten nur unter /v1.Pfad unter /v1 verwenden, siehe Endpunkte.
403 API access is not part of this subscriptionIhr Workspace nutzt kein Enterprise-Abo.Abo wechseln oder uns kontaktieren.
404Bot, Run oder Run-Gruppe gibt es in diesem Workspace nicht.ID mit /v1/bots, /v1/run-groups oder der Antwort des Starts vergleichen.
429Zu viele Anfragen, oder ein anderer Start Ihres Workspaces läuft noch.So viele Sekunden warten, wie Retry-After angibt, dann wiederholen.
Token-URL antwortet Invalid client or Invalid client credentialsClient ID oder Client Secret ist falsch, oder der Client wurde gelöscht.Werte prüfen oder das Secret ersetzen, siehe API-Clients verwalten.

Kommen Sie nicht weiter? Kontaktieren Sie uns mit der Client ID, dem Pfad und dem Zeitpunkt des Aufrufs.