API › Scans

Lancer un scan

Démarre un scan sur un site de ton projet, ou une analyse sur un dépôt GitHub. Le scan tourne en arrière-plan : la réponse arrive tout de suite (201, statut queued) et tu suis l'avancement avec Suivre un scan.

POSThttps://api.rustine.io/v1/targets/{target_id}/scans

Permission OAuth : scans:run · une clé d'API les a toutes

Ouvrir dans Claude Ouvrir dans ChatGPT

Un audit complet ne part que sur un site prouvé (DNS, fichier ou balise meta) : la loi interdit de tester un site qu'on ne contrôle pas. Sans preuve, demande un quick : Rustine lit seulement ce que tout visiteur voit. Si un scan du site tourne déjà, ou si un scan du même type a fini dans l'heure, tu reçois celui-là (200, reused: true) et rien n'est décompté.

Paramètres de chemin

target_idstringobligatoire
Le site ou le dépôt.

En-têtes

Idempotency-Keystringoptionnel
Une clé unique (1 à 255 caractères imprimables, un UUID convient) pour rejouer la requête sans risque : la première réponse est renvoyée pendant 24 heures ; la même clé avec une autre requête répond 409 idempotency_conflict.

Corps de la requête

kindstringoptionnel
Le type de scan : quick (par défaut pour un site) lit ce que tout visiteur voit, audit ajoute des contrôles en lecture seule (site prouvé, Solo et Pro), repository analyse un dépôt GitHub (le seul type, et le défaut, pour un dépôt).
quickauditrepository

Réponse

idstring
L'identifiant du scan.
objectstring
Le type d'objet, toujours le même pour une route donnée.
target_idstring
Le site ou le dépôt scanné.
kindstring
quick (ce que tout visiteur voit), audit (ajoute des contrôles en lecture seule, sites prouvés seulement) ou repository (analyse d'un dépôt GitHub).
quickauditrepository
statusstring
Les scans tournent en arrière-plan : interroge jusqu'à done ou failed.
queuedrunningdonefailed
scorenumber | null
Le score sur 100, une fois terminé.
gradestring | null
La note, une fois terminé.
ABCDF
coveragenumber | null
La part des contrôles qui ont pu tourner (de 0 à 1), une fois terminé.
audit_fallbackboolean
Un audit était demandé mais la preuve du site ne tenait plus : un scan rapide a tourné à la place, et aucun audit n'a été décompté.
reusedboolean
Vrai quand la requête a reçu un scan existant au lieu d'un nouveau (un en cours, ou un du même type dans l'heure) ; rien n'a été décompté.
next_real_scan_atstring | null
Avec reused pour un scan récent : quand un nouveau scan de ce type pourra partir.
created_atstring
Quand il a été demandé (ISO 8601, UTC).
finished_atstring | null
Quand il s'est terminé, null tant qu'il tourne.

Erreurs

Code	error.code	Ce qui se passe
400	body_invalid	Le corps de la requête n'est pas du JSON valable. Vérifie l'en-tête `Content-Type: application/json`.
400	parameter_invalid	Un paramètre manque ou n'est pas valable ; `param` le nomme.
400	target_kind_invalid	Le type de scan ne va pas avec la cible : `repository` pour un dépôt GitHub, `quick` ou `audit` pour un site.
400	idempotency_key_invalid	L'en-tête `Idempotency-Key` doit faire de 1 à 255 caractères imprimables.
401	authentication_required	Aucune clé dans la requête. Passe-la dans l'en-tête `Authorization: Bearer rst_…`, jamais dans l'adresse.
401	invalid_api_key	La clé ou le jeton OAuth est faux, révoqué ou expiré. Vérifie qu'il est copié en entier, ou crée une nouvelle clé.
402	api_plan_required	L'espace est sur l'offre Gratuite. L'API vient avec Pro, ou à l'essai 14 jours sur Solo.
402	api_trial_ended	L'essai de 14 jours de Solo est terminé. Passe à Pro : tes clés remarchent aussitôt.
402	audit_not_in_plan	L'offre Gratuite ne fait que des scans rapides ; l'audit complet vient avec Solo et Pro.
402	repositories_not_in_plan	L'analyse des dépôts GitHub vient avec Solo et Pro.
402	scan_quota_exceeded	Les scans rapides de la période sont épuisés, et il ne reste aucun crédit de pack.
402	audit_quota_exceeded	Les audits complets de la période sont épuisés, et il ne reste aucun crédit de pack.
402	project_paused	Le projet est en pause : ton offre couvre moins de projets que ton espace n'en a. Ses problèmes restent lisibles, mais rien de nouveau ne tourne.
402	domain_taken	Sur l'offre Gratuite, un domaine déjà suivi par un autre compte gratuit ne peut être ni ajouté ni scanné.
403	scope_missing	Le jeton OAuth n'a pas la permission que demande cette route (indiquée sur sa page). Reconnecte l'agent pour l'accorder. Une clé d'API a toutes les permissions.
404	resource_not_found	Rien avec cet identifiant dans l'espace de la clé. Un objet d'un autre espace répond pareil : son existence n'est jamais révélée.
409	proof_required	Le site doit d'abord être prouvé comme le tien (audit complet, correctif, marquage). Prouve-le dans l'app : DNS, fichier ou balise meta.
409	site_excluded	Le propriétaire de ce site a demandé à ne pas être scanné. Rustine ne le scannera pas.
409	github_unavailable	L'analyse des dépôts GitHub n'est pas disponible pour le moment.
409	idempotency_conflict	Cette `Idempotency-Key` a déjà servi pour une autre requête (méthode, chemin ou corps). Une nouvelle action prend une nouvelle clé.
409	idempotency_in_progress	Une requête avec cette `Idempotency-Key` est encore en cours. Réessaie dans un instant.
429	rate_limited	Trop de requêtes pour cette clé (120 par minute). Attends `Retry-After` secondes.
429	repository_analyses_limit_reached	L'espace a lancé beaucoup d'analyses de dépôt ces dernières 24 heures. Réessaie plus tard.
500	internal_error	Une erreur de notre côté, signalée automatiquement. Réessaie plus tard ; donne le `Request-Id` au support si elle revient.
503	service_unavailable	Rustine est indisponible un instant. Réessaie avec la même `Idempotency-Key`.
503	platform_busy	Rustine ne lance pas de nouveau scan pendant quelques minutes. Réessaie plus tard ; rien n'a été décompté.