openapi: 3.2.0
info:
  title: Ironfang Audit Rule Packs API
  version: 1.0.0
  summary: Website audits with findings and signed, independently timestamped evidence.
  description: Asynchronous website audits with signed, independently timestamped evidence.
  contact:
    name: Ironfang
    email: hello@ironfang.uk
    url: https://ironfang.com/contact
  termsOfService: https://ironfang.com/legal/terms
  license:
    name: Proprietary - use governed by the Ironfang terms of service
    url: https://ironfang.com/legal/terms
servers:
- url: https://api.ironfang.com/audit
  description: Production
security:
- bearerAuth: []
- apiKey: []
tags:
- name: RulePacks
  description: Installable rule packs.
paths:
  /v1/rule-packs:
    get:
      operationId: listRulePacks
      tags:
      - RulePacks
      summary: The rule pack catalogue
      description: 'Ironfang-maintained rule templates. A pack is a starting point, not a compliance product: each one states what it checks and, in the same breath, what it cannot tell you. Installing a pack copies rules into your own site, which you then own and can edit.'
      responses:
        '200':
          description: Packs
        '401':
          $ref: '#/components/responses/Problem'
          description: No credential, or one that is not accepted
        '403':
          $ref: '#/components/responses/Problem'
          description: The key's scopes or the person's role do not allow audit.read, or the request names another organisation
  /v1/rule-packs/installed/{installationId}/upgrade:
    parameters:
    - name: installationId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    post:
      operationId: upgradeRulePacksInstalledByInstallationId
      tags:
      - RulePacks
      summary: Upgrade an installed pack, or change its values
      description: The explicit action. Regenerates the pack's rules and writes the differences as ordinary revisions, so every change keeps its history. Rules the pack no longer ships are reported as orphaned and left alone rather than deleted, because you may still want the requirement.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                variables:
                  type: object
                  additionalProperties:
                    type: string
                  description: Omit to reuse the values given at install.
      responses:
        '200':
          description: What the upgrade changed
        '404':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
  /v1/rule-packs/installed/{installationId}:
    parameters:
    - name: installationId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    delete:
      operationId: deleteRulePacksInstalledByInstallationId
      tags:
      - RulePacks
      summary: Uninstall a pack
      description: Retires the rules it created. They stop being evaluated; they are not deleted, so every result that referenced one still resolves.
      responses:
        '204':
          description: Uninstalled
        '404':
          $ref: '#/components/responses/Problem'
components:
  responses:
    Problem:
      description: Problem response
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    description: Stable machine-readable code. Billing refusals use the codes every Ironfang product shares (BillingCode), with the same status and message whichever product answered; everything else is Ironfang Audit's own.
                  message:
                    type: string
                  docs:
                    type: string
                    format: uri
                    description: Where the errors are documented.
                    example: https://ironfang.com/audit/docs#errors
                  product:
                    type: string
                    description: 'Billing refusals only: the product the refused work belongs to (audit).'
                  meter:
                    type: string
                    description: 'Billing refusals only: the meter that refused, audit.capture or audit.retention_extension.'
                  reset_at:
                    type: string
                    format: date-time
                    description: 'Billing refusals only: when the free allowance renews (the next month''s start, UTC).'
              request_id:
                type: string
                description: The X-Ironfang-Request-ID of the failed request.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: if_live_ platform API key
      description: 'A platform API key minted in the portal (Warden). Its scopes are its

        permissions - `audit:read`, `audit:run`, `audit:manage`,

        `audit:evidence`, `audit:integrations`, or `audit:*` - and

        it acts only in the organisation it was minted for. Legacy Ironfang Render

        keys carry no Ironfang Audit scopes and are refused with 403.

        '
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Warden JWT
      description: 'A Warden user token. Each route also requires a tenant permission

        in the acting tenant, resolved live from Warden: read routes need

        `audit.read`; creating sites and rules `audit.manage`; queueing

        an audit `audit.run`; evidence bundles and raw artifacts

        `audit.evidence`; webhooks, export destinations and manual exports

        `audit.integrations`; billing changes `billing.manage`. A missing permission is 403; a permission

        lookup failure is 503.

        '
externalDocs:
  description: Ironfang Audit documentation
  url: https://ironfang.com/audit/docs