{
  "openapi": "3.0.3",
  "info": {
    "title": "PageSpeed Exporter API",
    "description": "Run live Google Lighthouse performance audits on any public URL and receive a complete, AI-ready JSON report. The report includes Performance, Accessibility, Best-Practices, and SEO scores; Core Web Vitals (LCP, FCP, CLS, TBT, Speed Index, TTI); CrUX real-user field data; stack-specific hints; and a prioritized list of opportunities and diagnostics with time/byte savings estimates.\n\nFree to use. Rate limits apply. Provide your own Google API key via the `apiKey` field to use your own quota.",
    "version": "1.0.0",
    "contact": {
      "name": "PageSpeed Exporter",
      "url": "https://speedexporter.com/contact"
    },
    "license": {
      "name": "Powered by Google PageSpeed Insights API",
      "url": "https://developers.google.com/speed/docs/insights/v5/get-started"
    }
  },
  "servers": [
    {
      "url": "https://speedexporter.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/analyze": {
      "post": {
        "operationId": "analyzeUrl",
        "summary": "Run a Lighthouse performance audit",
        "description": "Submits a URL to the Google PageSpeed Insights API and returns the complete performance report. The response is the raw PSI JSON (LighthouseResult) containing all audit data, metrics, scores, and CrUX field data.",
        "tags": ["Performance"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnalyzeRequest"
              },
              "example": {
                "url": "https://example.com",
                "strategy": "mobile"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful audit. Returns the full Google PageSpeed Insights API response (LighthouseResult).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PSIResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — malformed URL, unsupported protocol, or private/internal address.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "403": {
            "description": "Feature requires an upgraded plan (e.g. desktop analysis on the free tier).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UpgradeResponse" }
              }
            }
          },
          "429": {
            "description": "Monthly report limit exceeded or anonymous preview quota exhausted.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UpgradeResponse" }
              }
            }
          },
          "502": {
            "description": "The upstream Google PageSpeed Insights API returned an error.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "504": {
            "description": "The Google PageSpeed Insights API did not respond within 30 seconds.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "operationId": "mcpDiscovery",
        "summary": "MCP server discovery",
        "description": "Returns metadata about the MCP server and available tools. Use this endpoint to discover the MCP integration before connecting.",
        "tags": ["MCP"],
        "responses": {
          "200": {
            "description": "MCP server info and tool list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "version": { "type": "string" },
                    "description": { "type": "string" },
                    "mcp_endpoint": { "type": "string", "format": "uri" },
                    "docs": { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "mcpJsonRpc",
        "summary": "MCP JSON-RPC endpoint",
        "description": "Model Context Protocol (MCP) server using the 2024-11-05 spec. Supports `initialize`, `tools/list`, and `tools/call` methods. Add this endpoint to Claude Desktop or any MCP-compatible client to give AI agents direct access to Lighthouse performance audits.",
        "tags": ["MCP"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "examples": {
                "initialize": {
                  "summary": "MCP handshake",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "initialize",
                    "params": {
                      "protocolVersion": "2024-11-05",
                      "capabilities": {},
                      "clientInfo": { "name": "my-agent", "version": "1.0" }
                    }
                  }
                },
                "toolsList": {
                  "summary": "List available tools",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 2,
                    "method": "tools/list"
                  }
                },
                "analyzeUrl": {
                  "summary": "Run a Lighthouse audit",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 3,
                    "method": "tools/call",
                    "params": {
                      "name": "analyze_url",
                      "arguments": {
                        "url": "https://example.com",
                        "strategy": "mobile"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/JsonRpcResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AnalyzeRequest": {
        "type": "object",
        "required": ["url"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The public URL to audit. Must use http:// or https://. Private, localhost, and internal network addresses are blocked.",
            "example": "https://example.com"
          },
          "strategy": {
            "type": "string",
            "enum": ["mobile", "desktop"],
            "default": "mobile",
            "description": "Lighthouse emulation strategy. 'mobile' uses a mid-range mobile device on Slow 4G (Google's Core Web Vitals baseline). 'desktop' uses a desktop browser on a fast connection."
          },
          "apiKey": {
            "type": "string",
            "description": "Optional Google PageSpeed Insights API key. Use your own key to avoid shared quota limits. Get a free key at https://console.cloud.google.com"
          }
        }
      },
      "PSIResponse": {
        "type": "object",
        "description": "Raw Google PageSpeed Insights API response (LighthouseResult). Contains scores, audits, metrics, CrUX field data, and stack pack hints.",
        "properties": {
          "kind": { "type": "string" },
          "id": { "type": "string" },
          "analysisUTCTimestamp": { "type": "string", "format": "date-time" },
          "loadingExperience": {
            "type": "object",
            "description": "CrUX real-user field data for the specific URL"
          },
          "originLoadingExperience": {
            "type": "object",
            "description": "CrUX real-user field data for the entire origin"
          },
          "lighthouseResult": {
            "type": "object",
            "description": "Full Lighthouse Result (LHR) object",
            "properties": {
              "categories": {
                "type": "object",
                "description": "Scores for performance, accessibility, best-practices, seo (0–1 scale)"
              },
              "audits": {
                "type": "object",
                "description": "Map of audit ID to audit result. 150+ audits including Core Web Vitals, opportunities, and diagnostics."
              },
              "stackPacks": {
                "type": "array",
                "description": "Framework-specific hints (WordPress, React, Next.js, etc.)"
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "description": "Human-readable error message" }
        }
      },
      "UpgradeResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "upgradeRequired": { "type": "boolean" },
          "requiredTier": { "type": "string", "enum": ["starter", "pro"] },
          "used": { "type": "integer" },
          "limit": { "type": "integer" },
          "previewExhausted": { "type": "boolean" },
          "resetAt": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "oneOf": [{ "type": "string" }, { "type": "integer" }, { "type": "null" }] },
          "method": { "type": "string" },
          "params": { "type": "object" }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "oneOf": [{ "type": "string" }, { "type": "integer" }, { "type": "null" }] },
          "result": { "type": "object" },
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "integer" },
              "message": { "type": "string" }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Performance",
      "description": "Lighthouse performance audit endpoints"
    },
    {
      "name": "MCP",
      "description": "Model Context Protocol (MCP) server — connect AI agents directly to PageSpeed Exporter"
    }
  ]
}