Référence de l'API Ironfang Audit

Démarrage rapide

Créez un site dans le portail Ironfang (en anglais), ou directement via l'API. L'ID de site renvoyé sert à ajouter des règles et à lancer des audits.

curl -X POST https://api.ironfang.com/audit/v1/sites \
  -H "Authorization: Bearer $IRONFANG_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Finance",
    "url": "https://www.example.com"
  }'

Toute l'API existe aussi sous forme de collection Postman publique, générée à partir du contrat OpenAPI. Son dossier Getting started crée un site, déclenche un audit et en suit l'état ; la première requête ne demande aucune clé.

Exécuter dans Postman Voir la collection

Clés API

Une automatisation peut utiliser une clé API de la plateforme au lieu d'un jeton utilisateur : créez-la dans le portail avec les portées Ironfang Audit dont elle a besoin et envoyez-la comme jeton bearer. Une clé n'agit que dans l'organisation pour laquelle elle a été créée, et chaque portée correspond à une permission : audit:read, audit:run, audit:manage, audit:evidence, audit:integrations, ou audit:* pour toutes. Une clé sans portée Ironfang Audit est refusée avec 403 insufficient_scope.

Règles déterministes

Les règles conservent leur version exacte dans chaque résultat. Les bases prises en charge incluent : le texte contient ou ne contient pas, les expressions régulières, la présence et le texte d'éléments, les liens, les métadonnées, le statut HTTP, HTTPS et les en-têtes de réponse.

{
  "name": "Company number is present",
  "rule_type": "text_contains",
  "severity": "failure",
  "configuration": { "value": "12764014" }
}

Une défaillance du robot d'exploration est un état opérationnel de la preuve, pas l'échec d'une règle de conformité.

Cycle de vie d'un audit

queueddiscoveringcapturingfinalising evidencetimestampingcompleted

Les audits sont asynchrones. Utilisez l'ID d'audit permanent renvoyé pour interroger la ressource, ou consommez les webhooks de cycle de vie signés par HMAC. Les exports S3 et la livraison des webhooks réessaient indépendamment de la finalisation des preuves.

Chaîne de preuves

Chaque manifeste de page contient les hachages de sa capture d'écran brute, du HTML, du texte visible, des en-têtes et des métadonnées réseau. Les hachages des pages deviennent des feuilles de Merkle à séparation de domaine. Ironfang Audit signe le manifeste d'audit canonique avec Ed25519 et soumet le hachage racine de l'audit, et non le contenu du site, à une autorité d'horodatage RFC 3161.

Les captures brutes restent immuables. Les tuiles de capture d'écran et les rapports sont des dérivés de présentation dont la provenance est indiquée.

POST /verify/v1/bundles

Importez un ZIP de preuves avec Content-Type: application/zip, ou vérifiez-le entièrement hors ligne avec le vérificateur en ligne de commande.

Télécharger Ironfang Audit Verify Voir le code source Sommes de contrôle SHA-256

ironfang audit verify -bundle evidence.zip \
  -trusted-public-key audit-ed25519.pub \
  -tsa-ca tsa-chain.pem

Le vérificateur recalcule les hachages des artefacts, valide l'appartenance de chaque page à l'arbre de Merkle et contrôle la signature d'Ironfang Audit à l'aide d'une clé de signature approuvée de manière indépendante. Avec une AC TSA de confiance configurée, il valide aussi la réponse RFC 3161. La clé intégrée à un ZIP n'est jamais acceptée comme sa propre ancre de confiance.

Des builds pour Linux, macOS et Windows sont publiés sous licence Apache 2.0. Chaque version publiée inclut des sommes de contrôle et une provenance de build Sigstore signée.

GET /v1/sites

Liste tous les sites Ironfang Audit disponibles pour l'organisation courante.

POST /v1/sites

Enregistre un site web public et son périmètre d'exploration. La réponse contient l'ID de site permanent utilisé par les règles et les audits.

Champ	Type	Remarques
`url`	string	Obligatoire. URL publique HTTP ou HTTPS.
`name`	string	Nom affiché. Par défaut, le nom d'hôte du site.
`timezone`	string	Fuseau horaire IANA utilisé par le navigateur contrôlé. Par défaut, UTC.
`crawl_policy`	object	Facultatif. Hôtes autorisés, limites de pages et contrôles d'exploration.

GET /v1/sites/{siteId}

Renvoie un site et sa politique d'exploration actuelle.

GET /v1/sites/{siteId}/rules

Liste les règles déterministes versionnées configurées pour un site.

POST /v1/sites/{siteId}/rules

Crée la première version immuable d'une règle déterministe.

Champ	Type	Remarques
`name`	string	Obligatoire. Nom lisible de la règle.
`description`	string	Facultatif. Explication de l'exigence.
`rule_type`	string	Obligatoire. Type d'évaluateur déterministe.
`severity`	string	Sévérité du résultat. Par défaut, `failure`.
`configuration`	object	Obligatoire. Configuration utilisée par l'évaluateur choisi.

GET /v1/audits

Liste les audits de l'organisation courante. Passez site_id en paramètre de requête pour limiter la réponse à un site.

POST /v1/sites/{siteId}/audits

Admet un audit asynchrone et le met en file d'attente. Les pages qu'il peut capturer sont d'abord réservées sur votre compte de facturation : une exploration que votre quota gratuit ou vos limites d'utilisation ne couvrent qu'en partie reçoit les pages qui tiennent encore et s'arrête là, et une exploration pour laquelle rien ne tient est refusée avec un code de facturation, si bien qu'aucun audit n'existe. L'audit n'est facturé que pour les preuves de page qu'il finalise. Envoyez un en-tête Idempotency-Key lorsqu'un client peut réessayer la requête.

Champ	Type	Remarques
`trigger_type`	string	Origine de l'audit. Par défaut, `manual`.
`reason`	string	Facultatif. Motif lisible de l'audit.

GET /v1/audits/{auditId}

Interroge le statut de l'audit, son état de conformité, le nombre de pages et le hachage racine des preuves.

GET /v1/audits/{auditId}/pages

Liste les observations de pages capturées, les résultats des règles et la classification des modifications.

GET /v1/audits/{auditId}/evidence

Télécharge le ZIP de preuves vérifiable de manière indépendante une fois que l'audit a atteint completed ou partial. La réponse est de type application/zip.

GET /v1/artifacts/{artifactId}

Diffuse un artefact de preuve propre au locataire, avec son type de média enregistré.

GET /verify/v1/signing-keys

Renvoie le registre public des clés de signature utilisé par le vérificateur hébergé.

GET /v1/sites/{siteId}/monitors

Liste les moniteurs d'un site : ce qui est surveillé, à quelle fréquence, et quand la prochaine exécution est prévue.

POST /v1/sites/{siteId}/monitors

Crée un moniteur. mode vaut full_site (exploration) ou url_set (les pages de urls) ; cadence vaut manual, daily, six_hourly ou hourly, ouvert à chaque compte ; anchor_minute et timezone fixent le créneau quotidien. Chaque exécution planifiée est un audit complet, avec la même chaîne de preuves qu'un audit manuel. Chaque exécution est admise en entier à son créneau ; une exécution qui ne tient pas dans votre quota gratuit ou vos limites d'utilisation est ignorée, avec un événement monitor.skipped dont le reason est le code de facturation.

Champ de change_policy	Type	Remarques
`ignored_selectors`	string[]	Zones retirées du texte comparé (bannières de cookies, compteurs). Même sous-ensemble de sélecteurs que pour les règles.
`min_text_change`	number	Part des lignes (de 0 à 1) qui doivent différer pour que la page soit considérée comme modifiée.
`min_visual_change`	number	Part des pixels échantillonnés (de 0 à 1).
`ignore_numbers`	boolean	Masque les nombres et les dates qui changent à chaque visite.
`notify_only_on_rule_change`	boolean	Seul un changement de résultat d'une règle compte comme significatif.

La politique façonne la comparaison et la notification, jamais l'enregistrement : la capture d'écran brute, le HTML et le texte visible sont stockés intacts, et le texte normalisé est conservé à côté en tant que dérivé.

POST /v1/monitors/{monitorId}/run

Exécute le moniteur immédiatement. /pause, /resume et /archive changent le statut ; PUT /urls remplace l'ensemble de pages ; GET /runs liste les audits produits par le moniteur.

GET /v1/page-observations/{observationId}/comparison

Ce qui a changé par rapport à la capture précédente, calculé à partir des preuves stockées selon la politique de modification de l'audit : blocs de texte normalisé avec numéros de ligne, scores textuel et visuel, changements d'URL, de titre et de statut HTTP, résultats de règles qui ont changé, ID des artefacts de capture d'écran des deux côtés, et caractère significatif ou non de la modification. Une première capture n'a pas de côté précédent et en indique la raison.

GET /v1/pages/{pageId}/observations

L'historique d'une page d'un audit à l'autre, du plus récent au plus ancien. limit jusqu'à 200 ; passez le next_cursor renvoyé pour continuer.

GET /v1/audits/{auditId}/pages?change=changed&compliance=fail

La liste des pages accepte change (new, changed, moved, unchanged), compliance (pass, fail, error), capture (captured, failed) et q (sous-chaîne de l'URL ou du titre) ; chacun est une liste séparée par des virgules. total est le nombre non filtré.

GET /v1/events

Les événements récents de l'organisation (audit.started, audit.completed, audit.partial, audit.failed, change.detected, compliance.failed, monitor.skipped, evidence.expiring), avec la charge utile reçue par chaque webhook. Les enveloppes de webhook portent schema_version et l'ID de l'événement comme clé d'idempotence ; un endpoint est désactivé après 20 échecs consécutifs et réactivé avec PATCH /v1/webhooks/{endpointId} (enabled, events). DELETE retire un endpoint et conserve son historique ; POST .../deliveries/{deliveryId}/retry remet une livraison en file d'attente.

GET /v1/notification-preferences

Quels événements sont envoyés par e-mail, à qui, et s'ils partent immédiatement ou dans un récapitulatif quotidien (07:00 UTC). PUT avec events, recipients et digest ; les destinataires doivent être des membres actuels de l'organisation, et une clé API peut conserver la liste mais pas la modifier. Les e-mails contiennent des chiffres et un lien vers le portail, jamais de contenu capturé. GET /v1/notifications est le journal des envois.

GET /v1/webhooks

Liste les endpoints de webhook enregistrés pour l'organisation courante.

POST /v1/webhooks

Enregistre un endpoint HTTPS public. Le secret de signature HMAC est renvoyé une seule fois, dans la réponse de création.

Champ	Type	Remarques
`url`	string	Obligatoire. Destination HTTPS publique.
`events`	string[]	Par défaut, `audit.completed`.

GET /v1/export-destinations

Liste les destinations de preuves S3 et compatibles S3 configurées.

POST /v1/export-destinations

Crée une destination S3 chiffrée. Les champs obligatoires sont region, bucket, access_key et secret_key. Les champs facultatifs incluent endpoint, prefix, path_style, session_token et export_mode.

POST /v1/audits/{auditId}/exports

Met en file d'attente l'export d'un audit terminé vers la destination_id fournie.

GET /v1/usage

L'utilisation mesurée du mois, lue sur le compte de facturation de l'organisation : captures (audit.capture) et retention_extension (audit.retention_extension), chacun avec le quota gratuit, ce qui a été utilisé, ce que les audits admis réservent encore et le montant à ce jour, hors taxes. À côté figurent les données qui ne relèvent pas de la facturation : sites face à site_limit et max_pages_per_audit (des limites de capacité, identiques pour chaque compte), standard_retention_days, les octets hébergés et la prochaine expiration, ainsi qu'une projection des captures que vos moniteurs actifs peuvent demander ce mois-ci.

POST /v1/retention/quotes

Calcule le prix de la conservation des preuves hébergées d'audits choisis (audit_ids) ou d'artefacts (artifact_ids) pendant months mois entiers au-delà de chaque échéance actuelle. Le devis est un prix fixe tiré du catalogue des tarifs, hors taxes, et peut être acheté jusqu'à son expires_at, environ quinze minutes plus tard. Il ne déplace rien et ne facture rien par lui-même. Nécessite audit:read.

POST /v1/retention/purchases

Achète un devis exactement tel qu'il a été établi, avec son quote_id : toutes les échéances sont déplacées et l'utilisation est enregistrée en une seule étape, ou rien ne se passe. Il faut une personne connectée disposant des droits de facturation et d'une adresse e-mail vérifiée ; les clés API sont refusées. Un devis expiré, ou dont les preuves ont changé depuis, reçoit 409 quote_expired : demandez-en un nouveau. Rien ne se renouvelle de lui-même.

Erreurs

Chaque erreur renvoyée par une opération a la même forme JSON : un code stable, un message destiné aux personnes, un lien vers cette section et l'ID de la requête.

{
  "error": {
    "code": "evidence_not_final",
    "message": "the evidence bundle is available after evidence finalisation",
    "docs": "https://ironfang.com/audit/docs#errors"
  },
  "request_id": "01a0c375-6b34-7c1e-9b52-4f0a8d3e6c17"
}

Basez votre logique sur code et le statut HTTP : le code est stable et lisible par machine, tandis que message est rédigé pour les personnes et peut changer. De nouveaux codes peuvent être ajoutés ; traitez un code inconnu selon sa classe de statut. docs renvoie vers cette section. request_id reprend l'en-tête de réponse X-Ironfang-Request-ID ; communiquez-le au support et nous retrouverons la requête exacte.

Statut	Code	Signification
400	`invalid_json`, `invalid_query`	Le corps n'est pas une seule valeur JSON de la forme documentée (les champs inconnus sont refusés), ou un paramètre de requête est inconnu, répété ou mal formé.
401	`unauthorized`, `invalid_api_key`	Aucun jeton bearer, un jeton qui ne se vérifie pas, ou une clé API révoquée ou inconnue.
403	`forbidden`, `insufficient_scope`	Les portées de la clé ne couvrent pas la route, le rôle de la personne dans l'organisation ne le permet pas, ou la requête désigne une organisation dans laquelle l'identifiant ne peut pas agir. Quand une permission manque, le message la nomme.
404	`not_found`	Ce site, cette règle, cet audit, ce constat, ce moniteur, ce webhook ou cette destination d'export n'existe pas dans cette organisation. Un objet qui appartient à une autre organisation est signalé de la même manière.
409	`evidence_not_final`, `monitor_archived`, `rule_retired`, `pack_already_installed`, `quote_expired`	La requête est en conflit avec l'état de l'objet : le paquet de preuves a été demandé avant que l'audit n'atteigne `completed` ou `partial`, le moniteur est archivé, la règle est retirée, le pack de règles est déjà installé sur le site, ou un devis de conservation ne peut plus être acheté.
410	`evidence_expired`	Les preuves hébergées ont dépassé leur durée de conservation. Les hachages et les métadonnées de signature restent sur l'audit.
422	`invalid_url`, `unsafe_url`, `invalid_rule`, `invalid_cadence`, `invalid_webhook_url`	Le JSON est bien formé, mais une valeur n'est pas acceptable : une URL qui n'est pas en HTTP ou HTTPS public (HTTPS uniquement pour un webhook) ou qui ne se résout pas vers un hôte routable publiquement, une règle que son évaluateur ne peut pas accepter, une fréquence inconnue. Le message indique quelle valeur et pourquoi.
422	`site_limit`	L'organisation détient autant de sites que la limite de capacité le permet. Cette limite est la même pour chaque compte ; `GET /v1/usage` la renvoie dans `site_limit`.
402, 429	`free_allowance_exhausted`, `account_budget_exhausted`, `product_budget_exhausted`, `paid_usage_paused`, `payment_required`	Votre compte de facturation a refusé le travail avant qu'il ne commence : le quota gratuit est épuisé sans Pay as you go, une limite d'utilisation est atteinte, ou l'utilisation payante est en pause ou en attente d'un paiement. Rien n'a été réservé ni facturé. À côté du code, l'erreur porte `product`, `meter` et `reset_at`, le moment où le quota gratuit se renouvelle.
429	`rate_limited`	Le vérificateur hébergé limite les requêtes par adresse client. Attendez le nombre de secondes indiqué dans `Retry-After` avant de réessayer.
500, 503	`internal_error`, `permissions_unavailable`, `verifier_busy`	L'erreur vient de nous. Un 503 est temporaire (les permissions n'ont pas pu être vérifiées, ou le vérificateur est saturé) : réessayez sous peu. Pour un 500, communiquez le `request_id`.

Cette liste n'est pas exhaustive. Un 422 n'a pas de corps d'erreur : POST /verify/v1/bundles répond à un ZIP de preuves non valide par le rapport de vérification lui-même.

Interfaces pour machines

Interface	Détails
Page produit	https://ironfang.com/audit
Documentation	https://ironfang.com/audit/docs
URL de base de l'API	`https://api.ironfang.com/audit`
Contrat OpenAPI	https://api.ironfang.com/audit/openapi.yaml. Le même contrat est servi en JSON à `https://api.ironfang.com/audit/openapi.json`.
Authentification	Clé API de la plateforme comme jeton bearer
Erreurs	https://ironfang.com/audit/docs#errors. Un corps JSON avec un code stable, un message, ce lien et l'identifiant de la requête.
MCP	Disponible. Lire les sites, les audits, les constats, les règles et l'utilisation, et lancer un audit limité d'un site. La modification d'une règle, d'un site, d'une surveillance ou d'un constat reste dans le portail et l'API REST. Les outils sont nommés `audit.*`. Référence du serveur MCP ; chaque outil et chaque schéma, sans jeton, à /.well-known/ironfang-mcp.json
Découverte	/apis.json, /.well-known/api-catalog et /llms.txt

Lancé sous le nom Auditwolf. Les chemins d'API, scopes, noms d'outils et en-têtes portant ce nom ont été retirés le 28 septembre 2026 ; seuls les identifiants ci-dessous, enregistrés dans des preuves signées, le conservent.