{
    "openapi": "3.1.0",
    "info": {
        "title": "AgentSiteAudit API",
        "version": "1.2.0",
        "summary": "Website audits built for AI agents.",
        "description": "Send one URL, get back one structured JSON report: a score, a priority-ordered issue list, and for every check its result, severity, evidence and an exact fix. Audits are passive and refuse private, internal and reserved addresses. Every response, success or failure, uses the same 15-field envelope. Check IDs are permanent; ignore IDs and fields you do not recognise. Each audit costs $0.01 in USDC on Base, paid per request with the x402 protocol (HTTP 402 with a PAYMENT-REQUIRED header, then retry with a PAYMENT-SIGNATURE header). Charged only when an audit actually runs. Rate limits: 10 audits a minute and 500 a day per IP address.",
        "contact": {
            "name": "AgentSiteAudit",
            "email": "derek@agentsiteaudit.com",
            "url": "https://agentsiteaudit.com/"
        },
        "x-guidance": "Call GET /v1/audit?url=<page> when you need to know whether a web page is healthy, secure, findable and ready for AI agents, and exactly what to fix. After changes, call again with &previous=<audit_id> to confirm what was fixed. 0.01 USDC per call via x402 on Base; untested checks are never counted as passes."
    },
    "servers": [
        {
            "url": "https://agentsiteaudit.com"
        }
    ],
    "externalDocs": {
        "description": "Agent guide",
        "url": "https://agentsiteaudit.com/llms.txt"
    },
    "paths": {
        "/v1/audit": {
            "get": {
                "operationId": "auditWebsite",
                "summary": "Audit one web page",
                "description": "Fetches the page, its robots.txt, sitemap, referenced assets and up to 50 links, then returns the full report. Typical time is 1-4 seconds; the hard budget is 10 seconds. Read summary.score only when it is not null, and fix issues from the top of the issues array.",
                "parameters": [
                    {
                        "name": "url",
                        "in": "query",
                        "required": true,
                        "description": "Absolute http or https URL of the page to audit. Ports 80 and 443 only.",
                        "schema": {
                            "type": "string",
                            "format": "uri",
                            "maxLength": 2048
                        },
                        "example": "https://example.com/"
                    },
                    {
                        "name": "fresh",
                        "in": "query",
                        "required": false,
                        "description": "Set to 1 to skip the 10-minute cache and run a new audit, for example to confirm a fix.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "1"
                            ]
                        }
                    },
                    {
                        "name": "previous",
                        "in": "query",
                        "required": false,
                        "description": "Verify: the audit_id of an earlier audit of the same site, kept for 30 days. Runs a fresh audit and adds a comparison listing what was fixed, improved, still failing, worse, new and not re-checked. Same price as an audit. Unknown or other-site IDs return 400 before any payment.",
                        "schema": {
                            "type": "string",
                            "pattern": "^aud_[0-9A-Z]{26}$"
                        },
                        "example": "aud_01M6527XCRCB308T391BZGFZ9T"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The audit ran. Check status: complete, partial, or failed (the site could not be reached).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Report"
                                }
                            }
                        },
                        "headers": {
                            "X-Cache": {
                                "description": "HIT when served from the 10-minute cache, MISS when a new audit ran.",
                                "schema": {
                                    "type": "string",
                                    "enum": [
                                        "HIT",
                                        "MISS"
                                    ]
                                }
                            },
                            "Age": {
                                "description": "Seconds since a cached report was produced. Only sent on a HIT.",
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Rejected: invalid URL, scheme, host or port. status is rejected and error is set.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Report"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Rejected: the URL points to a private, internal or reserved address.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Report"
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. Use GET.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Report"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limited. Wait for the number of seconds in Retry-After.",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                },
                                "description": "Seconds to wait before retrying."
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Report"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Our error. Safe to retry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Report"
                                }
                            }
                        }
                    }
                },
                "x-payment-info": {
                    "price": {
                        "mode": "fixed",
                        "currency": "USD",
                        "amount": "0.010000"
                    },
                    "protocols": [
                        "x402"
                    ]
                },
                "tags": [
                    "website-audit",
                    "seo",
                    "security",
                    "accessibility",
                    "performance"
                ]
            }
        },
        "/v1/checks.json": {
            "get": {
                "operationId": "getCheckRegistry",
                "summary": "List every check",
                "description": "The published registry: every check ID, category, severity and threshold, plus severity weights, category weights, caps, coverage minimums and grade boundaries.",
                "responses": {
                    "200": {
                        "description": "The check registry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/v1/health": {
            "get": {
                "operationId": "getHealth",
                "summary": "Service status",
                "responses": {
                    "200": {
                        "description": "The service is up.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "status",
                                        "api_version",
                                        "rule_version"
                                    ],
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "const": "ok"
                                        },
                                        "api_version": {
                                            "type": "string"
                                        },
                                        "rule_version": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/v1/openapi.json": {
            "get": {
                "operationId": "getOpenApi",
                "summary": "This OpenAPI description",
                "responses": {
                    "200": {
                        "description": "The OpenAPI 3.1 document.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        }
    },
    "components": {
        "schemas": {
            "Report": {
                "type": "object",
                "description": "The fixed envelope returned by every response. All 15 core fields are always present. Audit responses also carry comparison: null, or the Verify result when previous is given.",
                "required": [
                    "schema_version",
                    "api_version",
                    "rule_version",
                    "audit_id",
                    "status",
                    "checked_at",
                    "duration_ms",
                    "target",
                    "summary",
                    "categories",
                    "issues",
                    "checks",
                    "data",
                    "limitations",
                    "error"
                ],
                "properties": {
                    "schema_version": {
                        "type": "string",
                        "examples": [
                            "1.0"
                        ]
                    },
                    "api_version": {
                        "type": "string",
                        "examples": [
                            "1.0.0"
                        ]
                    },
                    "rule_version": {
                        "type": "string",
                        "description": "Version of the check rules and scoring. Compare it before comparing scores across audits.",
                        "examples": [
                            "2026-10-28"
                        ]
                    },
                    "audit_id": {
                        "type": "string",
                        "pattern": "^aud_[0-9A-HJKMNP-TV-Z]{26}$"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "complete",
                            "partial",
                            "failed",
                            "rejected",
                            "error"
                        ]
                    },
                    "checked_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "duration_ms": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "target": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/Target"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "summary": {
                        "$ref": "#/components/schemas/Summary"
                    },
                    "categories": {
                        "type": "object",
                        "description": "Always contains all ten categories.",
                        "required": [
                            "security",
                            "seo",
                            "tls",
                            "performance",
                            "transport",
                            "accessibility",
                            "links",
                            "mobile",
                            "dns",
                            "agents"
                        ],
                        "additionalProperties": {
                            "$ref": "#/components/schemas/Category"
                        }
                    },
                    "issues": {
                        "type": "array",
                        "description": "IDs of FAIL and WARNING checks, most important first.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "checks": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Check"
                        }
                    },
                    "data": {
                        "type": "object",
                        "description": "Raw measurements keyed by category."
                    },
                    "limitations": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "examples": [
                            [
                                "no_browser_rendering",
                                "http3_not_supported_by_client"
                            ]
                        ]
                    },
                    "error": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/Error"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "comparison": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "description": "Present on audit responses. Null unless previous was given. Holds previous_audit_id, previous_checked_at, previous_rule_version, score {before, after, change}, grade {before, after}, all_resolved, counts, message, and the lists fixed, improved, still_failing, worse, new and not_rechecked. Each list item has id, severity, before, after, title and sometimes note. new_checks lists checks added to AgentSiteAudit since the earlier audit; they are not changes on the site."
                    }
                }
            },
            "Target": {
                "type": "object",
                "required": [
                    "requested_url",
                    "final_url",
                    "host",
                    "ip",
                    "http_status",
                    "redirects"
                ],
                "properties": {
                    "requested_url": {
                        "type": "string"
                    },
                    "final_url": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "host": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "ip": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "http_status": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "redirects": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "required": [
                                "url",
                                "status",
                                "location"
                            ],
                            "properties": {
                                "url": {
                                    "type": "string"
                                },
                                "status": {
                                    "type": "integer"
                                },
                                "location": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            },
            "Summary": {
                "type": "object",
                "required": [
                    "score",
                    "grade",
                    "score_basis",
                    "coverage",
                    "cap_applied",
                    "counts",
                    "issues_by_severity"
                ],
                "properties": {
                    "score": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "minimum": 0,
                        "maximum": 100,
                        "description": "Null when overall coverage is under 60% or the site could not be reached."
                    },
                    "grade": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "enum": [
                            "A",
                            "B",
                            "C",
                            "D",
                            "F",
                            null
                        ]
                    },
                    "score_basis": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "enum": [
                            "full",
                            "partial",
                            null
                        ]
                    },
                    "coverage": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1
                    },
                    "cap_applied": {
                        "oneOf": [
                            {
                                "type": "null"
                            },
                            {
                                "type": "object",
                                "required": [
                                    "limit",
                                    "reason",
                                    "uncapped_score",
                                    "checks"
                                ],
                                "properties": {
                                    "limit": {
                                        "type": "integer",
                                        "enum": [
                                            49,
                                            79
                                        ]
                                    },
                                    "reason": {
                                        "type": "string",
                                        "enum": [
                                            "critical_failure",
                                            "high_failure"
                                        ]
                                    },
                                    "uncapped_score": {
                                        "type": "integer"
                                    },
                                    "checks": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        ]
                    },
                    "counts": {
                        "type": "object",
                        "required": [
                            "total",
                            "pass",
                            "fail",
                            "warning",
                            "not_tested"
                        ],
                        "properties": {
                            "total": {
                                "type": "integer"
                            },
                            "pass": {
                                "type": "integer"
                            },
                            "fail": {
                                "type": "integer"
                            },
                            "warning": {
                                "type": "integer"
                            },
                            "not_tested": {
                                "type": "integer"
                            }
                        }
                    },
                    "issues_by_severity": {
                        "type": "object",
                        "required": [
                            "critical",
                            "high",
                            "medium",
                            "low",
                            "info"
                        ],
                        "properties": {
                            "critical": {
                                "type": "integer"
                            },
                            "high": {
                                "type": "integer"
                            },
                            "medium": {
                                "type": "integer"
                            },
                            "low": {
                                "type": "integer"
                            },
                            "info": {
                                "type": "integer"
                            }
                        }
                    }
                }
            },
            "Category": {
                "type": "object",
                "required": [
                    "score",
                    "weight",
                    "coverage",
                    "counts"
                ],
                "properties": {
                    "score": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "minimum": 0,
                        "maximum": 100
                    },
                    "weight": {
                        "type": "integer"
                    },
                    "coverage": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1
                    },
                    "counts": {
                        "type": "object",
                        "required": [
                            "pass",
                            "fail",
                            "warning",
                            "not_tested"
                        ],
                        "properties": {
                            "pass": {
                                "type": "integer"
                            },
                            "fail": {
                                "type": "integer"
                            },
                            "warning": {
                                "type": "integer"
                            },
                            "not_tested": {
                                "type": "integer"
                            }
                        }
                    }
                }
            },
            "Check": {
                "type": "object",
                "required": [
                    "id",
                    "category",
                    "result",
                    "severity",
                    "title",
                    "why",
                    "evidence",
                    "fix",
                    "fix_snippet",
                    "auto_fixable",
                    "confidence",
                    "not_tested_reason",
                    "docs_url",
                    "duration_ms"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Permanent check ID, category.subject.condition. Never renamed or reused.",
                        "examples": [
                            "seo.meta_description.present"
                        ]
                    },
                    "category": {
                        "type": "string",
                        "enum": [
                            "transport",
                            "tls",
                            "dns",
                            "performance",
                            "seo",
                            "links",
                            "accessibility",
                            "mobile",
                            "security"
                        ]
                    },
                    "result": {
                        "type": "string",
                        "enum": [
                            "PASS",
                            "WARNING",
                            "FAIL",
                            "NOT_TESTED"
                        ]
                    },
                    "severity": {
                        "type": "string",
                        "enum": [
                            "CRITICAL",
                            "HIGH",
                            "MEDIUM",
                            "LOW",
                            "INFO"
                        ]
                    },
                    "title": {
                        "type": "string"
                    },
                    "why": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "evidence": {
                        "$ref": "#/components/schemas/Evidence"
                    },
                    "fix": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "fix_snippet": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "auto_fixable": {
                        "type": "boolean",
                        "description": "True when an agent can apply the fix by editing the page or server config alone."
                    },
                    "confidence": {
                        "type": "string",
                        "enum": [
                            "high",
                            "medium",
                            "low"
                        ]
                    },
                    "not_tested_reason": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "enum": [
                            "not_applicable",
                            "deadline_exceeded",
                            "budget_exceeded",
                            "dependency_failed",
                            "fetch_failed",
                            "dns_lookup_failed",
                            "unsupported",
                            null
                        ]
                    },
                    "docs_url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "duration_ms": {
                        "type": "integer"
                    }
                }
            },
            "Evidence": {
                "type": "object",
                "required": [
                    "location",
                    "selector",
                    "observed",
                    "expected",
                    "items",
                    "items_total"
                ],
                "properties": {
                    "location": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "selector": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "observed": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "expected": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "items": {
                        "type": "array",
                        "maxItems": 20,
                        "items": {
                            "type": "string"
                        }
                    },
                    "items_total": {
                        "type": "integer"
                    }
                }
            },
            "Error": {
                "type": "object",
                "required": [
                    "code",
                    "message",
                    "retryable",
                    "retry_after_s"
                ],
                "properties": {
                    "code": {
                        "type": "string",
                        "examples": [
                            "invalid_url",
                            "blocked_destination",
                            "rate_limited",
                            "internal_error"
                        ]
                    },
                    "message": {
                        "type": "string"
                    },
                    "retryable": {
                        "type": "boolean"
                    },
                    "retry_after_s": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    }
                }
            }
        }
    },
    "tags": [
        {
            "name": "website-audit"
        },
        {
            "name": "seo"
        },
        {
            "name": "security"
        },
        {
            "name": "accessibility"
        },
        {
            "name": "performance"
        }
    ]
}