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 → 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, findings:read, findings:write et reports:read.

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.

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

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. 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 et 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 3$ done

3. Télécharger le rapport

Choisissez format=json pour la synthèse lisible par machine, markdown pour un rapport lisible, ou sarif pour SARIF 2.1.0.

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é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
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 et paginés	findings:read
GET	/orgs/{orgId}/audits/{auditId}/report	Rapport en json, markdown ou sarif	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.

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 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 ; la section Tarifs indique les valeurs actuelles.