Cognitive Accessibility Audit - API Contract

GET /api/v1/accessibility-audits/api/v1/accessibility-audits

List all accessibility audit reports (supports ?wizard_id= filter)

Public

Response Example

{
  "data": [
    {
      "audit_id": "audit-001",
      "audit_type": "wizard_config",
      "target_id": "onboarding-wizard-v3",
      "is_compliant": false,
      "violation_count": 2,
      "warning_count": 1,
      "run_at": "2026-03-26T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 14
  }
}

GET /api/v1/accessibility-audits/api/v1/accessibility-audits/:id

Get a full accessibility audit report by ID

Public

Response Example

{
  "audit_id": "audit-001",
  "audit_type": "wizard_config",
  "target_id": "onboarding-wizard-v3",
  "is_compliant": false,
  "violations": [
    {
      "rule": "max_choices_per_screen",
      "screen_id": "screen-01",
      "severity": "error",
      "message": "8 choices exceed the cognitive load limit of 7"
    },
    {
      "rule": "explicit_advance_required",
      "screen_id": "screen-01",
      "severity": "error",
      "message": "Auto-advance is not permitted"
    }
  ],
  "warnings": [
    {
      "rule": "preselected_default",
      "screen_id": "screen-03",
      "severity": "warning",
      "message": "Pre-selected answer may influence user choices"
    }
  ],
  "run_at": "2026-03-26T09:00:00Z"
}

POST /api/v1/accessibility-audits/api/v1/accessibility-audits

Run a new accessibility audit against a wizard config

Public

Request Example

{
  "audit_type": "wizard_config",
  "target_id": "onboarding-wizard-v3",
  "config": {
    "screens": [
      {
        "screen_id": "screen-01",
        "choices": [
          "A",
          "B",
          "C",
          "D"
        ],
        "advance_trigger": "button"
      }
    ]
  }
}

Response Example

{
  "audit_id": "audit-015",
  "audit_type": "wizard_config",
  "target_id": "onboarding-wizard-v3",
  "is_compliant": true,
  "violations": [],
  "warnings": [],
  "run_at": "2026-03-26T10:50:00Z"
}

PUT /api/v1/accessibility-audits/api/v1/accessibility-audits/:id

Update audit metadata (e.g. mark as reviewed or add notes)

Public

Request Example

{
  "reviewed_by": "usr-admin-003",
  "notes": "Acknowledged — will fix in v3.1",
  "status": "reviewed"
}

Response Example

{
  "audit_id": "audit-001",
  "status": "reviewed",
  "reviewed_by": "usr-admin-003",
  "notes": "Acknowledged — will fix in v3.1",
  "updated_at": "2026-03-26T11:00:00Z"
}

DELETE /api/v1/accessibility-audits/api/v1/accessibility-audits/:id

Delete an audit report

Public

Response Example

{
  "deleted": true,
  "audit_id": "audit-001"
}

POST /api/v1/accessibility-audits/api/v1/accessibility-audits/full

Run a full accessibility audit across all wizard configs and widget trees

Public

Request Example

{
  "include_widget_tree": true,
  "wizard_ids": [
    "onboarding-wizard-v3",
    "profile-wizard-v1"
  ]
}

Response Example

{
  "audit_id": "audit-016",
  "audit_type": "full",
  "is_compliant": false,
  "total_violations": 4,
  "total_warnings": 2,
  "audited_wizards": 2,
  "run_at": "2026-03-26T11:05:00Z"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}