Aller au contenu

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 basehttps://api.vetkit.dev/v1
OpenAPIhttps://api.vetkit.dev/v1/openapi.json — la référence complète et lisible par machine de chaque route et de chaque schéma
FormatCorps de requête et de réponse en JSON, horodatages ISO 8601, identifiants UUID
ErreursRFC 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.

Vérifier votre clé
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

Stockez vos clés dans le gestionnaire de secrets de votre fournisseur de CI, jamais dans le code. Le secret n’est affiché qu’une seule fois et n’est stocké que sous forme de hachage ; en cas de fuite, révoquez la clé dans l’application — la révocation est immédiate.

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.

Créer un audit
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. 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é.

Interroger avec curl et 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. 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).

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

Importez 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éthodeCheminDescriptionPortée
GET/meIdentifier la clé et son organisationquelconque
GET/orgs/{orgId}/reposLister les dépôts connectésrepos:read
POST/orgs/{orgId}/reposConnecter un dépôt par son URLrepos:write
GET/orgs/{orgId}/analyzersContrôles par suite, avec leur disponibilité et les valeurs par défautaudits:read
POST/orgs/{orgId}/auditsLancer un audit (202 Accepted)audits:write
GET/orgs/{orgId}/auditsLister les audits, filtrer par dépôt ou par statutaudits:read
GET/orgs/{orgId}/audits/{auditId}Statut, étapes et synthèse d’un auditaudits:read
POST/orgs/{orgId}/audits/{auditId}/cancelAnnuler un audit en file d’attente ou en coursaudits:write
DELETE/orgs/{orgId}/audits/{auditId}Supprimer définitivement un audit terminé et son rapportaudits:write
GET/orgs/{orgId}/audits/{auditId}/findingsConstats, filtrables par gravité, suite, catégorie et plus encore ; paginésfindings:read
GET/orgs/{orgId}/audits/{auditId}/reportRapport en json, markdown, sarif ou pdfreports: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.

Structure d’une page
{ "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.

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"}

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.

Demander un accès anticipé

Parlez-nous de votre équipe et des dépôts que vous souhaitez auditer. Nous ouvrons l’accès par petits groupes et vous répondrons par e-mail.

Nous utilisons ces informations uniquement pour répondre à votre demande. Politique de confidentialité