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 Arbeitsbereich-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, audits:run, findings:read, findings:write, findings:ai-fix, reports:read und agent:check.
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
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. Senden Sie "mode": "FULL" für einen vollständigen Scan; er verbraucht 1 Credit des Workspace-Inhabers und ist für eine andere ref als den Standard-Branch erforderlich. Ohne diese Angabe führt die API einen kostenlosen Quick Scan aus (posture, gitleaks und osv auf dem neuesten Commit des Standard-Branches), solange das monatliche Kontingent des Inhabers reicht. Ein vollständiger Scan ohne ausreichende Credits liefert 402 INSUFFICIENT_CREDITS.
analyzers legt die auszuführenden Prüfungen fest, aus der Suite Sicherheit (posture, gitleaks, secrets-history, osv, vendored, eol, supply-chain, sast, sast-community, bandit, gosec, rust-audit, iac, base-images, workflows), der Suite Codequalität (code-smells, complexity, duplication, tests, docs, accessibility, performance, hygiene), der Suite Nachhaltigkeit (licenses, dep-health, activity), der Suite KI-Code-Risiken (hallucinated-deps, ai-slop, vibe-stack, llm-app, ai-signal) und der Suite Produktionsreife (resilience, data-access, operability, openapi, web-assets). Die optionalen, unbewerteten Suites Datenschutz (Beta) (privacy-exposure, privacy-flows, privacy-lifecycle) und Git-Verlauf (git-history) wählen Sie auf dieselbe Weise aus. Ohne diesen Parameter werden die Standardprüfungen des Repositorys ausgeführt. GET /orgs/$ORG_ID/analyzers listet alle Prüfungen auf und gibt an, ob sie auf dem Server verfügbar sind; wird eine nicht verfügbare Prüfung angefordert, antwortet die API mit 422 ANALYZER_UNAVAILABLE.
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\", \"analyzers\": [\"gitleaks\", \"osv\", \"sast\"]}"{ "id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd", "status": "QUEUED", "ref": "main", "commitSha": "9f3c2e1b7a0d4c55e2f8a61b3d9c07e4a5b6f812", "repository": { "fullName": "acme/payments-api", "htmlUrl": "https://github.com/acme/payments-api" }, "analyzers": ["gitleaks", "osv", "sast"], "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, summary.suiteScores (Note und Score jeder ausgeführten Suite) sowie die Anzahl der Befunde nach Schweregrad.
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 3done3. Bericht herunterladen
Wählen Sie format=json für die maschinenlesbare Zusammenfassung, markdown für einen lesbaren Bericht, sarif für SARIF 2.1.0 oder pdf für einen druckfertigen Bericht (dessen Sprache legen Sie mit locale fest: en, de, es, fr, it, pt, ru oder tr).
curl "https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID/report?format=sarif" \ -H "Authorization: Bearer $VETKIT_API_KEY" \ -o vetkit.sarifLaden 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 |
| GET | /orgs/{orgId}/analyzers | Prüfungen nach Suite, mit Verfügbarkeit und Standardauswahl | audits:read |
| 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 nach Schweregrad, Suite, Kategorie und mehr; paginiert | findings:read |
| GET | /orgs/{orgId}/audits/{auditId}/report | Bericht als json, markdown, sarif oder pdf | 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.
{ "items": [ … ], "nextCursor": "eyJpZCI6…" }Fehler
Fehler verwenden application/problem+json mit einem stabilen, maschinenlesbaren code. Geben Sie die requestId an, wenn Sie den Support kontaktieren.
{ "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, INSUFFICIENT_CREDITS 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_LIMITzurü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.