{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Readiness Scanner",
    "version": "1.0.0",
    "summary": "Score any public website on how readable and transactable it is by AI agents.",
    "description": "Free, unauthenticated API that scores a public website on the Agent Readiness rubric: a 0-100 total across four pillars (discoverability, machine readability, transactability, trust and policy), mapped to a Level 0-3 readiness ladder, plus the highest-leverage gap and up to three prioritized fixes.\n\nThe same capability is available over the Model Context Protocol at https://agentreadyscore.vercel.app/mcp, which speaks revisions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26.",
    "contact": {
      "name": "Dave Rosemill",
      "url": "https://daverosemill.com",
      "email": "daverosemill@gmail.com"
    },
    "license": {
      "name": "Free to use",
      "identifier": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://agentreadyscore.vercel.app",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Agent-readiness service and paid audit",
    "url": "https://daverosemill.com/agent-ready"
  },
  "x-mcp": {
    "endpoint": "https://agentreadyscore.vercel.app/mcp",
    "transport": "streamable-http",
    "supportedVersions": [
      "2026-07-28",
      "2025-11-25",
      "2025-06-18",
      "2025-03-26"
    ],
    "tools": [
      {
        "name": "scan_agent_readiness",
        "description": "Scores a public website on how readable and transactable it is by AI agents. Returns a 0-100 total, a Level 0-3 readiness rating, four pillar scores (discoverability, machine readability, transactability, trust and policy), the single highest-leverage gap, and up to three prioritized fixes. Checks that do not apply to the site type are excluded rather than failed. Use this to diagnose why an agent cannot find, read, or buy from a site."
      }
    ]
  },
  "paths": {
    "/api/scan": {
      "post": {
        "operationId": "scanSite",
        "summary": "Score a site's agent readiness",
        "description": "Fetches the site's homepage, robots.txt, sitemap, llms.txt, and well-known paths, then scores it. Typically returns in under five seconds. No authentication and no rate limit key required.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "Site to scan. A bare hostname is accepted; https:// is assumed.",
                    "examples": [
                      "daverosemill.com",
                      "https://example.com"
                    ]
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scored result. A reachability failure also returns 200 with an `error` field set and no score, so callers should check for `error` first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "resolvedOrigin": {
                      "type": "string"
                    },
                    "score": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "level": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 3
                    },
                    "levelLabel": {
                      "type": "string",
                      "examples": [
                        "Level 2: Queryable"
                      ]
                    },
                    "levelDescription": {
                      "type": "string"
                    },
                    "pillars": {
                      "type": "object",
                      "properties": {
                        "discoverability": {
                          "type": "object",
                          "properties": {
                            "score": {
                              "type": "integer"
                            },
                            "max": {
                              "type": "integer"
                            },
                            "label": {
                              "type": "string"
                            },
                            "findings": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "string"
                                  },
                                  "points": {
                                    "type": "integer"
                                  },
                                  "earned": {
                                    "type": "boolean"
                                  },
                                  "detail": {
                                    "type": "string"
                                  },
                                  "applicable": {
                                    "type": "boolean",
                                    "description": "False when the check cannot apply to this kind of site, for example an e-commerce platform check against a service business. Non-applicable checks are excluded from the pillar denominator and from the report."
                                  }
                                },
                                "required": [
                                  "key",
                                  "label",
                                  "points",
                                  "earned"
                                ]
                              }
                            }
                          },
                          "required": [
                            "score",
                            "max",
                            "label",
                            "findings"
                          ]
                        },
                        "machineReadability": {
                          "type": "object",
                          "properties": {
                            "score": {
                              "type": "integer"
                            },
                            "max": {
                              "type": "integer"
                            },
                            "label": {
                              "type": "string"
                            },
                            "findings": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "string"
                                  },
                                  "points": {
                                    "type": "integer"
                                  },
                                  "earned": {
                                    "type": "boolean"
                                  },
                                  "detail": {
                                    "type": "string"
                                  },
                                  "applicable": {
                                    "type": "boolean",
                                    "description": "False when the check cannot apply to this kind of site, for example an e-commerce platform check against a service business. Non-applicable checks are excluded from the pillar denominator and from the report."
                                  }
                                },
                                "required": [
                                  "key",
                                  "label",
                                  "points",
                                  "earned"
                                ]
                              }
                            }
                          },
                          "required": [
                            "score",
                            "max",
                            "label",
                            "findings"
                          ]
                        },
                        "transactability": {
                          "type": "object",
                          "properties": {
                            "score": {
                              "type": "integer"
                            },
                            "max": {
                              "type": "integer"
                            },
                            "label": {
                              "type": "string"
                            },
                            "findings": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "string"
                                  },
                                  "points": {
                                    "type": "integer"
                                  },
                                  "earned": {
                                    "type": "boolean"
                                  },
                                  "detail": {
                                    "type": "string"
                                  },
                                  "applicable": {
                                    "type": "boolean",
                                    "description": "False when the check cannot apply to this kind of site, for example an e-commerce platform check against a service business. Non-applicable checks are excluded from the pillar denominator and from the report."
                                  }
                                },
                                "required": [
                                  "key",
                                  "label",
                                  "points",
                                  "earned"
                                ]
                              }
                            }
                          },
                          "required": [
                            "score",
                            "max",
                            "label",
                            "findings"
                          ]
                        },
                        "trustReadability": {
                          "type": "object",
                          "properties": {
                            "score": {
                              "type": "integer"
                            },
                            "max": {
                              "type": "integer"
                            },
                            "label": {
                              "type": "string"
                            },
                            "findings": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "string"
                                  },
                                  "points": {
                                    "type": "integer"
                                  },
                                  "earned": {
                                    "type": "boolean"
                                  },
                                  "detail": {
                                    "type": "string"
                                  },
                                  "applicable": {
                                    "type": "boolean",
                                    "description": "False when the check cannot apply to this kind of site, for example an e-commerce platform check against a service business. Non-applicable checks are excluded from the pillar denominator and from the report."
                                  }
                                },
                                "required": [
                                  "key",
                                  "label",
                                  "points",
                                  "earned"
                                ]
                              }
                            }
                          },
                          "required": [
                            "score",
                            "max",
                            "label",
                            "findings"
                          ]
                        }
                      }
                    },
                    "topGap": {
                      "type": "string"
                    },
                    "topGapDetail": {
                      "type": "string"
                    },
                    "reportFindings": {
                      "type": "array",
                      "maxItems": 3,
                      "items": {
                        "type": "object",
                        "properties": {
                          "priority": {
                            "type": "integer"
                          },
                          "title": {
                            "type": "string"
                          },
                          "detail": {
                            "type": "string"
                          },
                          "revenueFrame": {
                            "type": "string"
                          },
                          "effort": {
                            "type": "string",
                            "enum": [
                              "low",
                              "medium",
                              "high"
                            ]
                          }
                        }
                      }
                    },
                    "isShopify": {
                      "type": "boolean"
                    },
                    "shopifyStorefrontEligible": {
                      "type": "boolean"
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or unparseable body."
          },
          "500": {
            "description": "Unhandled server error."
          }
        }
      }
    },
    "/api/lead": {
      "post": {
        "operationId": "submitLead",
        "summary": "Request the full report by email",
        "description": "Attaches an email address to a completed scan so the full written report can be sent. Only for a human who wants the report; a scan itself needs no email.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "url": {
                    "type": "string"
                  },
                  "score": {
                    "type": "integer"
                  },
                  "level": {
                    "type": "integer"
                  },
                  "levelLabel": {
                    "type": "string"
                  }
                },
                "required": [
                  "email",
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing email or url."
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcpEndpoint",
        "summary": "Model Context Protocol endpoint (Streamable HTTP)",
        "description": "JSON-RPC 2.0 over HTTP POST. Exposes the scan capability as an MCP tool. Speaks revisions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26: modern requests carry protocol metadata in `params._meta`, legacy clients open with `initialize`. One message per POST; batching is not supported.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "const": "2.0"
                  },
                  "id": {
                    "type": [
                      "string",
                      "integer",
                      "null"
                    ]
                  },
                  "method": {
                    "type": "string",
                    "examples": [
                      "tools/list",
                      "tools/call"
                    ]
                  },
                  "params": {
                    "type": "object"
                  }
                },
                "required": [
                  "jsonrpc",
                  "method"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response."
          },
          "202": {
            "description": "Notification accepted; no body."
          },
          "400": {
            "description": "Header mismatch, unsupported version, or unparseable body."
          },
          "403": {
            "description": "Invalid Origin header."
          },
          "404": {
            "description": "Unknown JSON-RPC method (modern requests)."
          },
          "405": {
            "description": "GET and DELETE are not part of this revision."
          }
        }
      }
    }
  }
}