{
  "openapi": "3.1.1",
  "info": {
    "title": "Accessibility Fixer API",
    "version": "1.0.0",
    "summary": "Turn WCAG 2.2 problems in your HTML into concrete code fixes, grouped by effort.",
    "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
  },
  "servers": [
    {
      "url": "https://accessibilityfixer.usefulweb.site"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Turn WCAG 2.2 problems in your HTML into concrete code fixes, grouped by effort.",
        "description": "Paste HTML or enter a URL and get a fix list: for every detected accessibility problem the tool shows the offending element, a corrected version generated from it (alt text, labels, lang, names, heading levels, table headers…) and how much work it is. Placeholders that need human judgement are marked TODO, and a patch-style diff is included.\n\nMethodology:\n- Runs the same static rule set as Accessibility Snapshot (WCAG 2.2 mapping verified against the W3C Recommendation).\n- Each fix is generated from the actual element: the original start tag is re-serialised with the needed attribute added, changed or removed (e.g. alt, aria-label, lang, id + <label for>, th scope, tabindex).\n- Text the tool cannot know — what an image shows, what a field means, the page language — is never guessed: it is inserted as a TODO placeholder (lang=\"en\" is only a placeholder).\n- Fixes are grouped by effort: quick = attribute change, moderate = markup change that may affect styling, involved = structural or content work.\n\nAutomated static checks can only detect some failures. They cannot establish WCAG 2.2 conformance: conformance requires a full manual review of every page state (WCAG 2.2 §5.2), including rendered contrast, keyboard operation and assistive-technology testing.",
        "tags": [
          "high-value"
        ],
        "x-mcp-tool": "accessibility_fixer",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccessibilityFixerInput"
              },
              "examples": {
                "example1": {
                  "summary": "Checkout form with missing labels and alt text",
                  "value": {
                    "html": "<html>\n<head><title>Shop</title></head>\n<body>\n<header><a href=\"/\"><img src=\"/img/logo.svg\"></a></header>\n<main>\n<h1>Checkout</h1>\n<h4>Delivery address</h4>\n<form action=\"/pay\">\n  <input type=\"text\" name=\"fullname\" placeholder=\"Full name\">\n  <select name=\"country\"><option>Germany</option><option>France</option></select>\n  <button type=\"submit\"><i class=\"icon-arrow\"></i></button>\n</form>\n<img src=\"/img/IMG_2041.jpg\" alt=\"IMG_2041.jpg\">\n</main>\n</body>\n</html>",
                    "includeBestPractice": true,
                    "maxFixes": 80
                  }
                },
                "example2": {
                  "summary": "Pricing table, autoplay video and fake button",
                  "value": {
                    "html": "<!doctype html><html lang=\"de\"><head><title>Preise</title></head><body><main id=\"main\">\n<h1>Preise</h1>\n<table><tr><td>Tarif</td><td>Preis</td></tr><tr><td>Basis</td><td>9 €</td></tr><tr><td>Pro</td><td>19 €</td></tr></table>\n<video src=\"/promo.mp4\" autoplay></video>\n<div role=\"button\" class=\"buy\">Jetzt kaufen</div>\n</main></body></html>",
                    "includeBestPractice": false,
                    "maxFixes": 40
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccessibilityFixerResult"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid input (see errors[]).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tool": {
      "get": {
        "operationId": "getToolDefinition",
        "summary": "Inputs, output schema and examples for this tool",
        "responses": {
          "200": {
            "description": "Tool definition.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "AccessibilityFixerInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "url": {
            "title": "Page URL",
            "description": "Static HTML only; JavaScript is not executed.",
            "type": "string",
            "format": "uri"
          },
          "html": {
            "title": "Or paste HTML",
            "description": "Takes precedence over the URL.",
            "type": "string",
            "maxLength": 500000
          },
          "includeBestPractice": {
            "title": "Include best-practice and review items",
            "type": "boolean",
            "default": true
          },
          "maxFixes": {
            "title": "Max fixes",
            "type": "integer",
            "minimum": 5,
            "maximum": 300,
            "default": 80
          }
        },
        "required": []
      },
      "AccessibilityFixerResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "tool",
          "computedAt",
          "inputs",
          "summary",
          "result",
          "units",
          "assumptions",
          "sources",
          "warnings",
          "presentation",
          "links"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1.0"
          },
          "tool": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "version"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "description": "Normalised inputs actually used, including applied defaults."
          },
          "summary": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "origin",
              "totalFixes",
              "byEffort",
              "needsHumanInput",
              "fixes",
              "truncated",
              "patch",
              "conformanceStatement"
            ],
            "properties": {
              "origin": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "kind",
                  "truncated"
                ],
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "url",
                      "pasted"
                    ]
                  },
                  "requestedUrl": {
                    "type": "string"
                  },
                  "finalUrl": {
                    "type": "string"
                  },
                  "status": {
                    "type": "integer"
                  },
                  "contentType": {
                    "type": "string"
                  },
                  "fetchedAt": {
                    "type": "string"
                  },
                  "truncated": {
                    "type": "boolean"
                  }
                }
              },
              "totalFixes": {
                "type": "integer"
              },
              "byEffort": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "quick",
                  "moderate",
                  "involved"
                ],
                "properties": {
                  "quick": {
                    "type": "integer"
                  },
                  "moderate": {
                    "type": "integer"
                  },
                  "involved": {
                    "type": "integer"
                  }
                }
              },
              "needsHumanInput": {
                "type": "integer",
                "description": "Fixes that contain TODO placeholders (e.g. alt text, label wording, language code)."
              },
              "fixes": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "id",
                    "ruleId",
                    "wcag",
                    "kind",
                    "severity",
                    "effort",
                    "line",
                    "selector",
                    "problem",
                    "description",
                    "before",
                    "after",
                    "needsHumanInput"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "ruleId": {
                      "type": "string"
                    },
                    "wcag": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "failure",
                        "best-practice",
                        "needs-review"
                      ]
                    },
                    "severity": {
                      "type": "string",
                      "enum": [
                        "critical",
                        "serious",
                        "moderate",
                        "minor"
                      ]
                    },
                    "effort": {
                      "type": "string",
                      "enum": [
                        "quick",
                        "moderate",
                        "involved"
                      ]
                    },
                    "line": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "selector": {
                      "type": "string"
                    },
                    "problem": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "before": {
                      "type": "string"
                    },
                    "after": {
                      "type": "string"
                    },
                    "needsHumanInput": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "truncated": {
                "type": "boolean"
              },
              "patch": {
                "type": "string",
                "description": "Unified-diff style suggestion list keyed by source line."
              },
              "conformanceStatement": {
                "type": "string"
              }
            }
          },
          "units": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "retrievedAt": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "presentation": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Display blocks used by the human page (same data)."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "human",
              "api",
              "openapi",
              "methodology"
            ],
            "properties": {
              "human": {
                "type": "string",
                "format": "uri"
              },
              "api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}