Doc · API REST
API REST
Une API JSON sur HTTPS pour tout ce que fait l’application vetkit. Utilisez-la pour lancer des audits depuis la CI, conditionner vos mises en production à une note ou envoyer du SARIF vers GitHub code scanning.
Vue d’ensemble
| URL de base | https://api.vetkit.dev/v1 |
|---|---|
| OpenAPI | https://api.vetkit.dev/v1/openapi.json — la référence complète et lisible par machine de chaque route et de chaque schéma |
| Format | Corps de requête et de réponse en JSON, horodatages ISO 8601, identifiants UUID |
| Erreurs | RFC 9457 application/problem+json |
Cette page couvre l’essentiel. Générez un client ou parcourez les schémas un par un à partir du document OpenAPI ; le serveur MCP repose sur la même API.
Authentification
Créez une clé dans Paramètres de l’espace de travail → Clés d’API (propriétaires et administrateurs uniquement) et envoyez-la comme jeton Bearer. Une clé appartient à une seule organisation et dispose de portées explicites : repos:read, repos:write, audits:read, audits:write, audits:run, findings:read, findings:write, findings:ai-fix, reports:read et agent:check.
curl https://api.vetkit.dev/v1/me \ -H "Authorization: Bearer $VETKIT_API_KEY"La réponse indique les portées de la clé et, sous organizations, l’organisation à laquelle elle appartient — utilisez cet id comme ORG_ID ci-dessous.
Gardez vos clés hors du contrôle de version
Déroulé d’un audit
1. Lancer un audit
Transmettez l’identifiant d’un dépôt connecté et, facultativement, une branche, un tag ou un SHA de commit. Sans ref, c’est la branche par défaut qui est auditée. L’API répond 202 Accepted avec l’audit mis en file d’attente. Si un audit du même commit est déjà en cours, c’est celui-ci qui vous est renvoyé, et non un doublon. Envoyez "mode": "FULL" pour une analyse complète, qui utilise 1 crédit du propriétaire de l’espace de travail et est requise pour une ref autre que la branche par défaut. Sans ce paramètre, l’API lance un Quick Scan gratuit (posture, gitleaks et osv sur le dernier commit de la branche par défaut) tant que le quota mensuel du propriétaire le permet. Une analyse complète sans crédits suffisants renvoie 402 INSUFFICIENT_CREDITS.
analyzers sélectionne les contrôles à exécuter, parmi la suite Sécurité (posture, gitleaks, secrets-history, osv, vendored, eol, supply-chain, sast, sast-community, bandit, gosec, rust-audit, iac, base-images, workflows), la suite Qualité du code (code-smells, complexity, duplication, tests, docs, accessibility, performance, hygiene), la suite Pérennité (licenses, dep-health, activity), la suite Risques du code IA (hallucinated-deps, ai-slop, vibe-stack, llm-app, ai-signal) et la suite Prêt pour la production (resilience, data-access, operability, openapi, web-assets). Les suites optionnelles et non notées Confidentialité et protection des données (bêta) (privacy-exposure, privacy-flows, privacy-lifecycle) et Historique Git (git-history) se sélectionnent de la même manière. Omettez-le pour exécuter les contrôles par défaut du dépôt. GET /orgs/$ORG_ID/analyzers liste tous les contrôles et indique s’ils sont disponibles sur le serveur ; demander un contrôle indisponible renvoie 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. Interroger l’API jusqu’à la fin
Interrogez l’API toutes les quelques secondes jusqu’à ce que status vaille SUCCEEDED, FAILED ou CANCELLED. Un audit terminé inclut summary.grade, summary.overallScore, summary.suiteScores (note et score de chaque suite exécutée) ainsi que le nombre de constats par gravité.
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. Télécharger le rapport
Choisissez format=json pour la synthèse lisible par machine, markdown pour un rapport lisible, sarif pour du SARIF 2.1.0, ou pdf pour un rapport prêt à imprimer (définissez locale sur en, de, es, fr, it, pt, ru ou tr pour choisir sa langue).
curl "https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID/report?format=sarif" \ -H "Authorization: Bearer $VETKIT_API_KEY" \ -o vetkit.sarifImportez le fichier avec l’action github/codeql-action/upload-sarif de GitHub pour voir les constats dans les alertes code scanning de votre dépôt.
Endpoints principaux
Les chemins sont relatifs à https://api.vetkit.dev/v1. Consultez le document OpenAPI pour les paramètres et les schémas de réponse.
| Méthode | Chemin | Description | Portée |
|---|---|---|---|
| GET | /me | Identifier la clé et son organisation | quelconque |
| GET | /orgs/{orgId}/repos | Lister les dépôts connectés | repos:read |
| POST | /orgs/{orgId}/repos | Connecter un dépôt par son URL | repos:write |
| GET | /orgs/{orgId}/analyzers | Contrôles par suite, avec leur disponibilité et les valeurs par défaut | audits:read |
| POST | /orgs/{orgId}/audits | Lancer un audit (202 Accepted) | audits:write |
| GET | /orgs/{orgId}/audits | Lister les audits, filtrer par dépôt ou par statut | audits:read |
| GET | /orgs/{orgId}/audits/{auditId} | Statut, étapes et synthèse d’un audit | audits:read |
| POST | /orgs/{orgId}/audits/{auditId}/cancel | Annuler un audit en file d’attente ou en cours | audits:write |
| DELETE | /orgs/{orgId}/audits/{auditId} | Supprimer définitivement un audit terminé et son rapport | audits:write |
| GET | /orgs/{orgId}/audits/{auditId}/findings | Constats, filtrables par gravité, suite, catégorie et plus encore ; paginés | findings:read |
| GET | /orgs/{orgId}/audits/{auditId}/report | Rapport en json, markdown, sarif ou pdf | reports:read |
Connecter un dépôt dont le propriétaire n’a pas installé la GitHub App renvoie 409 INSTALLATION_REQUIRED avec un installUrl dans details.
Pagination
Les endpoints de liste sont paginés par curseur. Passez limit (1–100, 25 par défaut) et, pour la page suivante, la valeur nextCursor de la réponse précédente comme cursor. Un nextCursor à null signifie que vous avez atteint la fin.
{ "items": [ … ], "nextCursor": "eyJpZCI6…" }Erreurs
Les erreurs utilisent application/problem+json avec un code stable et lisible par machine. Indiquez le requestId lorsque vous contactez le support.
{ "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"}Codes courants : API_KEY_INVALID, API_KEY_REVOKED, API_KEY_EXPIRED, INSUFFICIENT_SCOPE, VALIDATION_FAILED, NOT_FOUND, INSTALLATION_REQUIRED, AUDIT_CONCURRENCY_LIMIT, INSUFFICIENT_CREDITS et RATE_LIMITED.
Limites de débit
- Par clé : 60 requêtes par minute par défaut, configurable jusqu’à 600 lors de la création de la clé.
- Audits simultanés : jusqu’à 3 audits en file d’attente ou en cours par organisation ; au-delà, l’API renvoie
409 AUDIT_CONCURRENCY_LIMIT. - Lancements d’audits : 30 par heure et par organisation.
Le dépassement d’une limite de débit renvoie 429 RATE_LIMITED avec un en-tête Retry-After — attendez ce nombre de secondes avant de réessayer. Les limites peuvent évoluer pendant la bêta.