API-Referenz

Schnellstart

Legen Sie eine Website im Ironfang-Portal (auf Englisch) an, oder direkt über die API. Die zurückgegebene Website-ID verwenden Sie, wenn Sie Regeln hinzufügen und Audits starten.

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

Die gesamte API gibt es auch als öffentliche Postman-Collection, erzeugt aus dem OpenAPI-Vertrag. Ihr Ordner Getting started legt eine Website an, startet ein Audit und fragt seinen Stand ab; die erste Anfrage braucht keinen Schlüssel.

In Postman ausführenCollection ansehen

API-Schlüssel

Automatisierungen können statt eines Benutzer-Tokens einen Plattform-API-Schlüssel verwenden: Erstellen Sie ihn im Portal mit den Berechtigungen für Ironfang Audit, die er braucht, und senden Sie ihn als Bearer-Token. Ein Schlüssel handelt nur in der Organisation, für die er erstellt wurde, und jede Berechtigung steht für eine Befugnis: audit:read, audit:run, audit:manage, audit:evidence, audit:integrations oder audit:* für alle. Ein Schlüssel ohne Berechtigung für Ironfang Audit wird mit 403 insufficient_scope abgewiesen.

Deterministische Regeln

Regeln behalten in jedem Ergebnis ihre genaue Version. Zu den unterstützten Grundlagen gehören: Text enthält oder enthält nicht, reguläre Ausdrücke, Vorhandensein und Text von Elementen, Links, Metadaten, HTTP-Status, HTTPS und Antwort-Header.

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

Ein Fehler des Crawlers ist ein betrieblicher Zustand des Nachweises, keine fehlgeschlagene Compliance-Regel.

Lebenszyklus eines Audits

Audits laufen asynchron. Fragen Sie die Ressource mit der zurückgegebenen dauerhaften Audit-ID ab, oder verarbeiten Sie HMAC-signierte Webhooks zum Lebenszyklus. S3-Exporte und die Webhook-Zustellung wiederholen Fehlversuche unabhängig vom Abschluss der Nachweise.

Nachweiskette

Jedes Seitenmanifest enthält die Hashes des unbearbeiteten Screenshots, des HTML, des sichtbaren Texts, der Header und der Netzwerkmetadaten. Die Seiten-Hashes werden zu domänengetrennten Merkle-Blättern. Ironfang Audit signiert das kanonische Audit-Manifest mit Ed25519 und übermittelt den Wurzel-Hash des Audits, nicht die Inhalte der Website, an eine Zeitstempelstelle nach RFC 3161.

Die unbearbeiteten Erfassungen bleiben unveränderlich. Screenshot-Kacheln und Berichte sind abgeleitete Darstellungen mit Herkunftsnachweis.

POST /verify/v1/bundles

Laden Sie ein Nachweis-ZIP mit Content-Type: application/zip hoch, oder prüfen Sie es vollständig offline mit dem Prüfwerkzeug für die Befehlszeile.

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

Das Prüfwerkzeug berechnet die Artefakt-Hashes neu, prüft für jede Seite die Zugehörigkeit zum Merkle-Baum und prüft die Signatur von Ironfang Audit gegen einen unabhängig als vertrauenswürdig festgelegten Signaturschlüssel. Ist eine vertrauenswürdige TSA-CA konfiguriert, prüft es auch die Antwort nach RFC 3161. Der in einem ZIP eingebettete Schlüssel wird nie als sein eigener Vertrauensanker akzeptiert.

Builds für Linux, macOS und Windows werden unter Apache 2.0 veröffentlicht. Jedes Release enthält Prüfsummen und eine signierte Build-Provenienz von Sigstore.

GET /v1/sites

Listet alle Websites in Ironfang Audit auf, die der aktuellen Organisation zur Verfügung stehen.

POST /v1/sites

Registriert eine öffentliche Website und ihre Crawl-Grenze. Die Antwort enthält die dauerhafte Website-ID, die Regeln und Audits verwenden.

GET /v1/sites/{siteId}

Liefert eine Website und ihre aktuelle Crawl-Richtlinie.

GET /v1/sites/{siteId}/rules

Listet die versionierten deterministischen Regeln auf, die für eine Website konfiguriert sind.

POST /v1/sites/{siteId}/rules

Erstellt die erste unveränderliche Version einer deterministischen Regel.

GET /v1/audits

Listet die Audits der aktuellen Organisation auf. Übergeben Sie site_id als Query-Parameter, um die Antwort auf eine Website zu beschränken.

POST /v1/sites/{siteId}/audits

Lässt ein asynchrones Audit zu und stellt es in die Warteschlange. Zuerst werden die Seiten, die es erfassen darf, auf Ihrem Abrechnungskonto reserviert: Ein Crawl, den Ihr kostenloses Kontingent oder Ihre Nutzungslimits nur teilweise abdecken, erhält die Seiten, die noch hineinpassen, und endet dort; einer, für den nichts mehr passt, wird mit einem Abrechnungscode abgelehnt, und es entsteht kein Audit. Berechnet werden nur die Seitennachweise, die das Audit abschließt. Senden Sie einen Header Idempotency-Key, wenn ein Client die Anfrage wiederholen könnte.

GET /v1/audits/{auditId}

Fragt Status, Compliance-Zustand, Seitenzahlen und den Wurzel-Hash der Nachweise eines Audits ab.

GET /v1/audits/{auditId}/pages

Listet erfasste Seitenbeobachtungen, Regelergebnisse und die Einstufung der Änderungen auf.

GET /v1/audits/{auditId}/evidence

Lädt das unabhängig prüfbare Nachweis-ZIP herunter, sobald das Audit completed oder partial erreicht hat. Die Antwort ist application/zip.

GET /v1/artifacts/{artifactId}

Streamt ein einzelnes, mandantenbezogenes Nachweisartefakt mit seinem aufgezeichneten Medientyp.

GET /verify/v1/signing-keys

Liefert das öffentliche Verzeichnis der Signaturschlüssel, das das gehostete Prüfwerkzeug verwendet.

GET /v1/sites/{siteId}/monitors

Listet die Monitore einer Website auf: was überwacht wird, wie oft und wann der nächste Lauf fällig ist.

POST /v1/sites/{siteId}/monitors

Erstellt einen Monitor. mode ist full_site (Crawl) oder url_set (die Seiten in urls); cadence ist manual, daily, six_hourly oder hourly, offen für jedes Konto; anchor_minute und timezone legen den täglichen Zeitpunkt fest. Jeder geplante Lauf ist ein vollständiges Audit mit derselben Nachweiskette wie ein manuelles. Jeder Lauf wird zu seinem Termin vollständig zugelassen; ein Lauf, der nicht in Ihr kostenloses Kontingent oder Ihre Nutzungslimits passt, wird mit einem Ereignis monitor.skipped übersprungen, dessen reason der Abrechnungscode ist.

Die Richtlinie bestimmt den Vergleich und die Benachrichtigung, nie die Aufzeichnung: Der unbearbeitete Screenshot, das HTML und der sichtbare Text werden unverändert gespeichert, und der normalisierte Text wird als abgeleitete Fassung daneben aufbewahrt.

POST /v1/monitors/{monitorId}/run

Startet sofort einen Lauf. /pause, /resume und /archive ändern den Status; PUT /urls ersetzt die Seitenmenge; GET /runs listet die Audits auf, die der Monitor erzeugt hat.

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

Was sich gegenüber der vorherigen Erfassung geändert hat, berechnet aus den gespeicherten Nachweisen nach der Änderungsrichtlinie des Audits: normalisierte Textabschnitte mit Zeilennummern, Text- und Bildwerte, Änderungen an URL, Titel und HTTP-Status, geänderte Regelergebnisse, die IDs der Screenshot-Artefakte beider Vergleichsseiten und ob die Änderung wesentlich war. Eine erste Erfassung hat keine vorherige Vergleichsseite und nennt den Grund.

GET /v1/pages/{pageId}/observations

Der Verlauf einer Seite über Audits hinweg, die neuesten zuerst. limit bis 200; übergeben Sie den zurückgegebenen next_cursor, um fortzufahren.

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

Die Seitenliste akzeptiert change (new, changed, moved, unchanged), compliance (pass, fail, error), capture (captured, failed) und q (Teilzeichenfolge von URL oder Titel); jeder Parameter ist eine kommagetrennte Liste. total ist die ungefilterte Anzahl.

GET /v1/events

Die letzten Ereignisse der Organisation (audit.started, audit.completed, audit.partial, audit.failed, change.detected, compliance.failed, monitor.skipped, evidence.expiring) mit der Nutzlast, die jeder Webhook erhalten hat. Webhook-Umschläge enthalten schema_version und die Ereignis-ID als Idempotenzschlüssel; ein Endpunkt wird nach 20 aufeinanderfolgenden Fehlschlägen deaktiviert und mit PATCH /v1/webhooks/{endpointId} (enabled, events) wieder aktiviert. DELETE legt einen Endpunkt still und behält seinen Verlauf; POST .../deliveries/{deliveryId}/retry stellt eine Zustellung erneut in die Warteschlange.

GET /v1/notification-preferences

Welche Ereignisse per E-Mail verschickt werden, an wen und ob sofort oder als eine tägliche Zusammenfassung (07:00 UTC). PUT mit events, recipients und digest; Empfänger müssen aktuelle Mitglieder der Organisation sein, und ein API-Schlüssel darf die Liste beibehalten, aber nicht ändern. E-Mails enthalten Zahlen und einen Link ins Portal, nie erfasste Inhalte. GET /v1/notifications ist das Versandprotokoll.

GET /v1/webhooks

Listet die Webhook-Endpunkte auf, die für die aktuelle Organisation registriert sind.

POST /v1/webhooks

Registriert einen öffentlichen HTTPS-Endpunkt. Das HMAC-Signaturgeheimnis wird einmalig in der Antwort auf die Erstellung zurückgegeben.

GET /v1/export-destinations

Listet die konfigurierten Nachweisziele in S3 und S3-kompatiblem Speicher auf.

POST /v1/export-destinations

Erstellt ein verschlüsseltes S3-Ziel. Pflichtfelder sind region, bucket, access_key und secret_key. Zu den optionalen Feldern gehören endpoint, prefix, path_style, session_token und export_mode.

POST /v1/audits/{auditId}/exports

Stellt ein abgeschlossenes Audit mit der übergebenen destination_id zum Export in die Warteschlange.

GET /v1/usage

Die gemessene Nutzung dieses Monats vom Abrechnungskonto der Organisation: captures (audit.capture) und retention_extension (audit.retention_extension), jeweils mit dem kostenlosen Kontingent, dem Verbrauchten, dem, was zugelassene Audits noch reserviert halten, und den bisherigen Kosten vor Steuern. Daneben stehen die Angaben, die nicht zur Abrechnung gehören: sites gegenüber site_limit und max_pages_per_audit (Kapazitätslimits, für jedes Konto gleich), standard_retention_days, gehostete Bytes und der nächste Ablauf sowie eine projection der Erfassungen, die Ihre aktiven Monitore in diesem Monat anfordern können.

POST /v1/retention/quotes

Berechnet den Preis dafür, die gehosteten Nachweise ausgewählter Audits (audit_ids) oder Artefakte (artifact_ids) months volle Monate über ihre jeweilige Frist hinaus aufzubewahren. Das Angebot ist ein Festpreis aus dem Preiskatalog, vor Steuern, und kann bis zu seinem expires_at gekauft werden, etwa fünfzehn Minuten später. Es verschiebt nichts und berechnet nichts von selbst. Erfordert audit:read.

POST /v1/retention/purchases

Kauft ein Angebot genau so, wie es angeboten wurde, mit seiner quote_id: Alle Fristen verschieben sich und die Nutzung wird in einem Schritt erfasst, oder es geschieht nichts. Erforderlich ist eine angemeldete Person mit Abrechnungsrechten und bestätigter E-Mail-Adresse; API-Schlüssel werden abgelehnt. Ein Angebot, das abgelaufen ist oder dessen Nachweise sich seitdem geändert haben, wird mit 409 quote_expired beantwortet: Fordern Sie ein neues an. Nichts verlängert sich von selbst.

Fehler

Jeder Fehler, den eine Operation zurückgibt, hat dieselbe JSON-Form: einen stabilen Code, eine Meldung für Menschen, einen Link auf diesen Abschnitt und die Anfrage-ID.

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

Verzweigen Sie anhand von code und dem HTTP-Status: Der Code ist stabil und maschinenlesbar, während message für Menschen geschrieben ist und sich ändern kann. Neue Codes können hinzukommen; behandeln Sie einen unbekannten Code nach seiner Statusklasse. docs verweist auf diesen Abschnitt. request_id wiederholt den Antwort-Header X-Ironfang-Request-ID; nennen Sie ihn dem Support, dann finden wir genau diese Anfrage.

Die Liste ist nicht vollständig. Ein 422 hat keinen Fehlerinhalt: POST /verify/v1/bundles beantwortet ein ungültiges Nachweis-ZIP mit dem Prüfbericht selbst.

Maschinenschnittstellen

Gestartet als Auditwolf. API-Pfade, Scopes, Tool-Namen und Header unter diesem Namen wurden am 28. September 2026 eingestellt; nur die folgenden, in signierten Nachweisen festgehaltenen Kennungen tragen ihn noch.