Ü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
curlundjq.
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.
Klicken Sie auf API-Client anlegen.
Geben Sie einen Name ein, zum Beispiel
CI-Pipeline(höchstens 64 Zeichen).Wählen Sie die Berechtigungsstufe:
Berechtigungsstufe Erlaubt Ergebnisse lesen Bots, Testfälle, Tags, Runs und Ergebnisse lesen. Runs starten und Ergebnisse lesen Alles aus Ergebnisse lesen und zusätzlich Runs starten. Klicken Sie auf Anlegen. Der Dialog zeigt Client ID, Client Secret, Token-URL und ein fertiges Beispiel.
Kopieren Sie das Client Secret in Ihren Secret-Speicher, zum Beispiel in die geschützten Variablen Ihrer CI-Pipeline.
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)" "$@"; }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}'Runs starten, hier alle Testfälle eines Tags. Statt
tag_idsgehen auchbot_ids(alle Testfälle eines Bots) undcase_ids(einzelne Testfälle), auch kombiniert.bot_typeist Pflicht:chatbotodervoicebot.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
202enthältrun_group_idund dierun_idsder gestarteten Runs. Schlägt der Start fehl, gibt die letzte Zeile die Fehlermeldung aus und bricht ab.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) doneErgebnisse 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=2usw. weiter, bispage * 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
| Methode | Pfad | Liefert | Stufe |
|---|---|---|---|
| GET | /v1/bots | Alle Chat- und Voicebots, nach Name sortiert | Ergebnisse lesen |
| GET | /v1/cases | Testfälle, seitenweise. Filter bot_id und tag_id | Ergebnisse lesen |
| GET | /v1/tags | Alle Tags, nach Name sortiert | Ergebnisse lesen |
| POST | /v1/runs | Startet einen Run pro ausgewähltem Testfall | Runs starten |
| GET | /v1/runs/{id} | Ein Run mit Bewertungen, Detailvergleichen und Transkript | Ergebnisse lesen |
| GET | /v1/run-groups | Run-Gruppen, neueste zuerst, seitenweise | Ergebnisse lesen |
| GET | /v1/run-groups/{id} | Eine Run-Gruppe mit Status und Anzahl Runs pro Status | Ergebnisse lesen |
| GET | /v1/run-groups/{id}/runs | Die Runs einer Gruppe mit Bewertungen und Transkripten, seitenweise | Ergebnisse lesen |
| GET | /v1/openapi.yaml | Die OpenAPI-Beschreibung | ohne Token |
- Seiten:
pagebeginnt bei 1,sizeist standardmäßig 20 und höchstens 100, bei/v1/run-groups/{id}/runshöchstens 50. Die Antwort enthältitems,page,sizeundtotal. - Status einer Run-Gruppe:
running, bis alle Runs fertig sind. Danachfailed, wenn ein Run fehlgeschlagen oder mit einem Fehler beendet ist, sonstpassed. - Status eines Runs:
newundinvoked(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}/runsfehlt 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
429mit dem HeaderRetry-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 sehen | Ursache | Lösung |
|---|---|---|
400 mit unknown field | Der 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 tag | Keine Auswahl im Body. | Mindestens eine ID in bot_ids, case_ids oder tag_ids angeben. |
401 authorization failed | Das Token fehlt, ist abgelaufen oder ungültig. | Neues Token anfordern, siehe Schritt 2. |
402 | Das monatliche Kontingent oder Budget Ihres Abos erlaubt keine weiteren Runs. | Verbrauch und Budget unter Billing prüfen. |
403 forbidden beim Start von Runs | Der Client hat die Stufe Ergebnisse lesen. | Client mit der Stufe Runs starten und Ergebnisse lesen verwenden. |
403 forbidden auf einem Pfad unter /api | Tokens von API-Clients gelten nur unter /v1. | Pfad unter /v1 verwenden, siehe Endpunkte. |
403 API access is not part of this subscription | Ihr Workspace nutzt kein Enterprise-Abo. | Abo wechseln oder uns kontaktieren. |
404 | Bot, Run oder Run-Gruppe gibt es in diesem Workspace nicht. | ID mit /v1/bots, /v1/run-groups oder der Antwort des Starts vergleichen. |
429 | Zu 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 credentials | Client 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.