{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentDots site audit",
    "version": "1.0.0",
    "description": "Checks whether AI agents can find, read, understand and act on a public website. Sixteen weighted checks, a score out of 100 and a letter grade. Ten audits per network every ten minutes; results are cached for ten minutes.",
    "contact": { "email": "desk@agentdots.org", "url": "https://agentdots.org/audit/" }
  },
  "servers": [{ "url": "https://agentdots.org" }],
  "paths": {
    "/api/audit": {
      "get": {
        "operationId": "auditSite",
        "summary": "Audit a website for AI agent readiness",
        "parameters": [
          { "name": "url", "in": "query", "required": true, "description": "Domain or URL of a public website on port 80 or 443, e.g. example.com", "schema": { "type": "string", "maxLength": 300 } }
        ],
        "responses": {
          "200": { "description": "Audit report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } },
          "400": { "description": "Invalid or refused address (error: invalid | blocked)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limit reached (error: rate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "502": { "description": "The site could not be reached (error: unreachable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Report": {
        "type": "object",
        "required": ["url", "score", "grade", "checkedAt", "checks"],
        "properties": {
          "url": { "type": "string", "format": "uri" },
          "score": { "type": "integer", "minimum": 0, "maximum": 100 },
          "grade": { "type": "string", "enum": ["A", "B", "C", "D", "F"] },
          "checkedAt": { "type": "string", "format": "date-time" },
          "cached": { "type": "boolean" },
          "checks": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "group", "weight", "status"],
              "properties": {
                "id": { "type": "string", "enum": ["https", "robots", "aiBots", "contentSignal", "sitemap", "llms", "markdown", "textInHtml", "headings", "lang", "canonical", "structuredData", "metaTags", "openGraph", "forms", "apiCatalog"] },
                "group": { "type": "string", "enum": ["find", "read", "understand", "act"] },
                "weight": { "type": "integer" },
                "status": { "type": "string", "enum": ["pass", "partial", "fail"] },
                "detail": { "type": "string" }
              }
            }
          }
        }
      },
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string", "enum": ["invalid", "blocked", "rate", "unreachable", "server"] } } }
    }
  }
}