Zum Inhalt springen

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-URLhttps://api.vetkit.dev/v1
OpenAPIhttps://api.vetkit.dev/v1/openapi.json — die vollständige, maschinenlesbare Referenz für jede Route und jedes Schema
FormatJSON-Bodys für Anfragen und Antworten, ISO-8601-Zeitstempel, UUIDs als IDs
FehlerRFC 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.

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

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\", \"analyzers\": [\"gitleaks\", \"osv\", \"sast\"]}"
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" },  "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.

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 3done

3. 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).

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.

MethodePfadBeschreibungScope
GET/meSchlüssel und seine Organisation identifizierenbeliebig
GET/orgs/{orgId}/reposVerbundene Repositorys auflistenrepos:read
POST/orgs/{orgId}/reposRepository per URL verbindenrepos:write
GET/orgs/{orgId}/analyzersPrüfungen nach Suite, mit Verfügbarkeit und Standardauswahlaudits:read
POST/orgs/{orgId}/auditsAudit starten (202 Accepted)audits:write
GET/orgs/{orgId}/auditsAudits auflisten, nach Repository oder Status filternaudits:read
GET/orgs/{orgId}/audits/{auditId}Status, Schritte und Zusammenfassung eines Auditsaudits:read
POST/orgs/{orgId}/audits/{auditId}/cancelEingereihtes oder laufendes Audit abbrechenaudits:write
DELETE/orgs/{orgId}/audits/{auditId}Abgeschlossenes Audit samt Bericht endgültig löschenaudits:write
GET/orgs/{orgId}/audits/{auditId}/findingsBefunde, filterbar nach Schweregrad, Suite, Kategorie und mehr; paginiertfindings:read
GET/orgs/{orgId}/audits/{auditId}/reportBericht als json, markdown, sarif oder pdfreports: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, 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_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.

Early Access anfordern

Erzählen Sie uns kurz von Ihrem Team und den Repositorys, die Sie prüfen möchten. Wir nehmen Teams in kleinen Gruppen auf und antworten per E-Mail.

Wir verwenden diese Angaben nur, um auf Ihre Anfrage zu antworten. Datenschutzerklärung