Auditwolf API reference

Quickstart

Create a site in the Ironfang portal, or create it directly through the API. The returned site ID is used when adding rules and starting audits.

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

Deterministic rules

Rules retain their exact version in every result. Supported foundations include text contains or does not contain, regular expressions, element presence and text, links, metadata, HTTP status, HTTPS and response headers.

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

A crawler failure is operational evidence state, not a failed compliance rule.

Audit lifecycle

queued

discovering

capturing

finalising evidence

timestamping

completed

Audits are asynchronous. Use the returned permanent audit ID to poll the resource or consume HMAC-signed lifecycle webhooks. S3 exports and webhook delivery retry independently from evidence completion.

Evidence chain

Each page manifest contains the hashes of its raw screenshot, HTML, visible text, headers and network metadata. Page hashes become domain-separated Merkle leaves. Auditwolf signs the canonical audit manifest with Ed25519 and submits the audit root hash, not website content, to an RFC 3161 timestamp authority.

Raw captures remain immutable. Screenshot tiles and reports are presentation derivatives with provenance.

POST /verify/v1/bundles

Upload an evidence ZIP with Content-Type: application/zip, or verify it fully offline with the command-line verifier.

Download Auditwolf Verify View source SHA-256 checksums

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

The verifier recalculates artifact hashes, validates every page's Merkle membership and checks the Auditwolf signature against an independently trusted signing key. With a configured trusted TSA CA it also validates the RFC 3161 response. The key embedded in a ZIP is never accepted as its own trust anchor.

Linux, macOS and Windows builds are published under Apache 2.0. Each release includes checksums and signed Sigstore build provenance.

GET /v1/sites

List every Auditwolf site available to the current organisation.

POST /v1/sites

Field	Type	Notes
`url`	string	Required public HTTP or HTTPS URL.
`name`	string	Display name. Defaults to the website hostname.
`timezone`	string	IANA timezone used by the controlled browser. Defaults to UTC.
`crawl_policy`	object	Optional allowed hosts, page limits and crawl controls.

GET /v1/sites/{siteId}

Return one site and its current crawl policy.

GET /v1/sites/{siteId}/rules

List the versioned deterministic rules configured for a site.

POST /v1/sites/{siteId}/rules

Create the first immutable version of a deterministic rule.

Field	Type	Notes
`name`	string	Required human-readable rule name.
`description`	string	Optional explanation of the requirement.
`rule_type`	string	Required deterministic evaluator type.
`severity`	string	Result severity. Defaults to `failure`.
`configuration`	object	Required configuration consumed by the selected evaluator.

GET /v1/audits

List audits for the current organisation. Supply site_id as a query parameter to restrict the response to one site.

POST /v1/sites/{siteId}/audits

Queue an asynchronous audit. Supply an Idempotency-Key header when a client may retry the request.

Field	Type	Notes
`trigger_type`	string	Origin of the audit. Defaults to `manual`.
`reason`	string	Optional human-readable reason for the audit.

GET /v1/audits/{auditId}

Poll the audit status, compliance state, page counts and evidence root hash.

GET /v1/audits/{auditId}/pages

List captured page observations, rule outcomes and change classifications.

GET /v1/audits/{auditId}/evidence

Download the independently verifiable evidence ZIP after the audit reaches completed or partial. The response is application/zip.

GET /v1/artifacts/{artifactId}

Stream one tenant-scoped evidence artifact using its recorded media type.

GET /verify/v1/signing-keys

Return the public signing-key ledger used by the hosted verifier.

GET /v1/webhooks

List webhook endpoints registered for the current organisation.

POST /v1/webhooks

Field	Type	Notes
`url`	string	Required public HTTPS destination.
`events`	string[]	Defaults to `audit.completed`.

GET /v1/export-destinations

List configured S3 and S3-compatible evidence destinations.

POST /v1/export-destinations

Create an encrypted S3 destination. Required fields are region, bucket, access_key and secret_key. Optional fields include endpoint, prefix, path_style, session_token and export_mode.

POST /v1/audits/{auditId}/exports

Queue a completed audit for export using the supplied destination_id.

GET /v1/usage

Return the organisation's total captured pages, audits and consumed page-capture credits.