Doku · REST-API

REST-API

Eine JSON-über-HTTPS-API für alles, was die vetkit-App kann. Nutzen Sie sie, um Audits aus der CI zu starten, Releases von einer Note abhängig zu machen oder SARIF in GitHub Code Scanning zu übertragen.

Überblick

Basis-URL	`https://api.vetkit.dev/v1`
OpenAPI	`https://api.vetkit.dev/v1/openapi.json` — die vollständige, maschinenlesbare Referenz für jede Route und jedes Schema
Format	JSON-Bodys für Anfragen und Antworten, ISO-8601-Zeitstempel, UUIDs als IDs
Fehler	RFC 9457 `application/problem+json`

Diese Seite behandelt das Wesentliche. Generieren Sie einen Client oder sehen Sie sich einzelne Schemas im OpenAPI-Dokument an; der MCP-Server basiert auf derselben API.

Authentifizierung

Erstellen Sie einen Schlüssel unter Einstellungen → API-Schlüssel (nur Inhaber und Admins) und senden Sie ihn als Bearer-Token. Schlüssel gehören zu genau einer Organisation und haben explizite Scopes: repos:read, repos:write, audits:read, audits:write, findings:read, findings:write und reports:read.

Schlüssel prüfen

$ curl https://api.vetkit.dev/v1/me \  -H "Authorization: Bearer $VETKIT_API_KEY"

Die Antwort listet die Scopes des Schlüssels und unter organizations die Organisation, zu der er gehört — verwenden Sie deren id unten als ORG_ID.

Schlüssel nicht in die Versionskontrolle

Speichern Sie Schlüssel im Secret-Store Ihres CI-Anbieters, niemals im Code. Das Secret wird nur einmal angezeigt und ausschließlich als Hash gespeichert; falls es offengelegt wird, widerrufen Sie es in der App — der Widerruf wirkt sofort.

Audit Schritt für Schritt

1. Audit starten

Übergeben Sie die ID eines verbundenen Repositorys und optional einen Branch, Tag oder Commit-SHA. Ohne ref wird der Standard-Branch geprüft. Die API antwortet mit 202 Accepted und dem eingereihten Audit. Läuft für denselben Commit bereits ein Audit, erhalten Sie dieses zurück statt eines Duplikats.

Audit erstellen

$ curl -X POST https://api.vetkit.dev/v1/orgs/$ORG_ID/audits \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -H "Content-Type: application/json" \  -d "{\"repositoryId\": \"$REPO_ID\", \"ref\": \"main\"}"

202 Accepted

{  "id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",  "status": "QUEUED",  "ref": "main",  "commitSha": "9f3c2e1b7a0d4c55e2f8a61b3d9c07e4a5b6f812",  "repository": { "fullName": "acme/payments-api", "htmlUrl": "https://github.com/acme/payments-api" },  "steps": [],  "summary": null}

2. Abfragen, bis es fertig ist

Fragen Sie alle paar Sekunden ab, bis status den Wert SUCCEEDED, FAILED oder CANCELLED hat. Ein abgeschlossenes Audit enthält summary.grade, summary.overallScore und die Anzahl der Befunde je Schweregrad.

Abfragen mit curl und jq

$ while :; do$   STATUS=$(curl -s https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID \    -H "Authorization: Bearer $VETKIT_API_KEY" | jq -r .status)$   echo "$STATUS"$   case "$STATUS" in SUCCEEDED|FAILED|CANCELLED) break ;; esac$   sleep 3$ done

3. Bericht herunterladen

Wählen Sie format=json für die maschinenlesbare Zusammenfassung, markdown für einen lesbaren Bericht oder sarif für SARIF 2.1.0.

SARIF herunterladen

$ curl "https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID/report?format=sarif" \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -o vetkit.sarif

Laden Sie die Datei mit der GitHub-Action github/codeql-action/upload-sarif hoch, um die Befunde in den Code-Scanning-Warnungen Ihres Repositorys zu sehen.

Wichtige Endpunkte

Pfade sind relativ zu https://api.vetkit.dev/v1. Parameter und Antwortschemas finden Sie im OpenAPI-Dokument.

Methode	Pfad	Beschreibung	Scope
GET	/me	Schlüssel und seine Organisation identifizieren	beliebig
GET	/orgs/{orgId}/repos	Verbundene Repositorys auflisten	repos:read
POST	/orgs/{orgId}/repos	Repository per URL verbinden	repos:write
POST	/orgs/{orgId}/audits	Audit starten (202 Accepted)	audits:write
GET	/orgs/{orgId}/audits	Audits auflisten, nach Repository oder Status filtern	audits:read
GET	/orgs/{orgId}/audits/{auditId}	Status, Schritte und Zusammenfassung eines Audits	audits:read
POST	/orgs/{orgId}/audits/{auditId}/cancel	Eingereihtes oder laufendes Audit abbrechen	audits:write
DELETE	/orgs/{orgId}/audits/{auditId}	Abgeschlossenes Audit samt Bericht endgültig löschen	audits:write
GET	/orgs/{orgId}/audits/{auditId}/findings	Befunde, filterbar und paginiert	findings:read
GET	/orgs/{orgId}/audits/{auditId}/report	Bericht als json, markdown oder sarif	reports:read

Wenn Sie ein Repository verbinden, auf dessen Konto die GitHub App nicht installiert ist, erhalten Sie 409 INSTALLATION_REQUIRED mit einer installUrl in details.

Paginierung

Listen-Endpunkte verwenden Cursor-Paginierung. Übergeben Sie limit (1–100, Standard 25) und für die nächste Seite den nextCursor aus der vorherigen Antwort als cursor. Ist nextCursor null, haben Sie das Ende erreicht.

Aufbau einer Seite

{ "items": [ … ], "nextCursor": "eyJpZCI6…" }

Fehler

Fehler verwenden application/problem+json mit einem stabilen, maschinenlesbaren code. Geben Sie die requestId an, wenn Sie den Support kontaktieren.

403 Forbidden

{  "type": "https://vetkit.dev/problems/insufficient-scope",  "title": "Forbidden",  "status": 403,  "detail": "This API key is missing the audits:write scope.",  "code": "INSUFFICIENT_SCOPE",  "requestId": "req_01J9Z3K8V4M2"}

Häufige Codes: API_KEY_INVALID, API_KEY_REVOKED, API_KEY_EXPIRED, INSUFFICIENT_SCOPE, VALIDATION_FAILED, NOT_FOUND, INSTALLATION_REQUIRED, AUDIT_CONCURRENCY_LIMIT und RATE_LIMITED.

Rate-Limits

Pro Schlüssel: standardmäßig 60 Anfragen pro Minute, beim Erstellen des Schlüssels auf bis zu 600 einstellbar.
Gleichzeitige Audits: bis zu 3 eingereihte oder laufende Audits pro Organisation; darüber hinaus wird 409 AUDIT_CONCURRENCY_LIMIT zurückgegeben.
Audit-Starts: 30 pro Stunde und Organisation.

Bei Überschreitung eines Rate-Limits wird 429 RATE_LIMITED mit einem Retry-After-Header zurückgegeben — warten Sie so viele Sekunden, bevor Sie es erneut versuchen. Die Limits können sich während der Beta ändern; der Abschnitt „Preise“ nennt die aktuellen Werte.