{
  "openapi": "3.1.0",
  "info": {
    "title": "Brante Dev Solutions API & Agent Gateway",
    "version": "1.0.0",
    "description": "Public and agent-accessible REST API for website speed diagnostics (WPO), WordPress security hardening, and technical scoping. Versioned under /v1/ path prefix. Public sandbox endpoints require zero authentication (security: []). Deprecations are announced 6 months in advance via HTTP Sunset and Deprecation headers.",
    "x-free-tier": true,
    "x-sandbox-environment": "https://brante.dev/api/v1/diagnostico",
    "x-deprecation-policy": "https://brante.dev/developers#versioning",
    "contact": {
      "name": "Benjamín Brante Pardo",
      "email": "hola@brante.dev",
      "url": "https://brante.dev"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://brante.dev",
      "description": "Production edge API gateway (Cloudflare Pages)"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Health and operational status probe",
        "description": "Returns operational readiness and edge infrastructure version. Zero-authentication public endpoint.",
        "operationId": "getHealth",
        "security": [],
        "parameters": [
          {
            "name": "verbose",
            "in": "query",
            "required": false,
            "description": "Optional flag to return detailed infrastructure telemetry",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Service is operational and ready to process requests",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal service error",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "summary": "v1 Health and operational status probe",
        "description": "Versioned operational readiness probe for automated agents and monitoring systems. Zero-authentication public endpoint.",
        "operationId": "getHealthV1",
        "security": [],
        "parameters": [
          {
            "name": "verbose",
            "in": "query",
            "required": false,
            "description": "Optional flag to return detailed infrastructure telemetry",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Service is operational",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal service error",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/diagnostico": {
      "get": {
        "summary": "Probe WPO Diagnostic Protocol and Capabilities",
        "description": "Returns capabilities, sandbox parameters, and supported protocols of the diagnostic engine. Zero-authentication public endpoint.",
        "operationId": "probeDiagnosticV1",
        "security": [],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": false,
            "description": "Optional target website URL to pre-validate capabilities for",
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Diagnostic metadata and supported capabilities",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiagnosticProbeResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required for advanced enterprise batch scanning (x402 protocol)",
            "headers": {
              "WWW-Authenticate": {
                "schema": { "type": "string" },
                "description": "x402 challenge parameters"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Execute Core Web Vitals & WPO Diagnostic",
        "description": "Evaluates a public website URL for performance bottlenecks, LCP, CLS, INP, and WordPress security headers. Open sandbox with free tier access.",
        "operationId": "runDiagnosticV1",
        "security": [],
        "requestBody": {
          "required": true,
          "description": "Target website URL payload for performance analysis",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DiagnosticRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Diagnostic evaluation generated successfully",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiagnosticResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input parameters (e.g. malformed URL)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required (x402 protocol)",
            "headers": {
              "WWW-Authenticate": {
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "headers": {
              "Retry-After": { "$ref": "#/components/headers/Retry-After" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "500": {
            "description": "Analysis execution failed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/diagnostico": {
      "get": {
        "summary": "Probe Core Web Vitals Diagnostic (Legacy Alias)",
        "description": "Legacy unversioned alias for /api/v1/diagnostico. Deprecated in favor of versioned /api/v1/ prefix.",
        "operationId": "probeDiagnosticLegacy",
        "deprecated": true,
        "security": [],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": false,
            "description": "Optional target website URL to pre-validate capabilities for",
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Diagnostic probe information with RFC 8594 deprecation headers",
            "headers": {
              "Deprecation": {
                "schema": { "type": "string" },
                "description": "RFC 8594 deprecation indicator"
              },
              "Sunset": {
                "schema": { "type": "string" },
                "description": "RFC 8594 sunset timestamp when this legacy alias will be removed"
              },
              "Link": {
                "schema": { "type": "string" },
                "description": "Link pointing to successor version /api/v1/diagnostico"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiagnosticProbeResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Run Core Web Vitals Diagnostic (Legacy Alias)",
        "description": "Legacy unversioned alias for /api/v1/diagnostico. Deprecated in favor of /api/v1/diagnostico.",
        "operationId": "runDiagnosticLegacy",
        "deprecated": true,
        "security": [],
        "parameters": [
          {
            "name": "dryRun",
            "in": "query",
            "required": false,
            "description": "Optional simulation dry-run flag",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Target website URL payload for performance analysis",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DiagnosticRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Diagnostic evaluation generated with RFC 8594 deprecation headers",
            "headers": {
              "Deprecation": {
                "schema": { "type": "string" },
                "description": "RFC 8594 deprecation indicator"
              },
              "Sunset": {
                "schema": { "type": "string" },
                "description": "RFC 8594 sunset date when this legacy route will be retired"
              },
              "Link": {
                "schema": { "type": "string" },
                "description": "Link pointing to successor version /api/v1/diagnostico"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiagnosticResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/pay": {
      "get": {
        "summary": "x402 Payment Facilitator Specification",
        "description": "Provides machine-readable payment parameters, supported currencies, and wallet targets for micropayments. Zero-authentication endpoint.",
        "operationId": "getPaymentRequirements",
        "security": [],
        "parameters": [
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "description": "Optional ISO-4217 currency filter (e.g. USD, CLP)",
            "schema": {
              "type": "string",
              "default": "USD"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Payment facilitator metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentFacilitatorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required specification",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "summary": "Model Context Protocol JSON-RPC 2.0 gateway",
        "description": "Executes MCP tools (wpo_diagnostic, project_scoper, health_check) and reads resources via Model Context Protocol JSON-RPC 2.0.",
        "operationId": "callMcpRpc",
        "security": [],
        "requestBody": {
          "required": true,
          "description": "JSON-RPC 2.0 MCP request payload",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["jsonrpc", "method"],
                "properties": {
                  "jsonrpc": { "type": "string", "example": "2.0" },
                  "id": { "type": ["string", "number", "null"], "example": 1 },
                  "method": { "type": "string", "example": "resources/list" },
                  "params": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 MCP response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": { "type": "string" },
                    "id": { "type": ["string", "number", "null"] },
                    "result": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimit-Limit": {
        "schema": { "type": "integer" },
        "description": "The maximum number of requests allowed in the current time window."
      },
      "RateLimit-Remaining": {
        "schema": { "type": "integer" },
        "description": "The number of requests remaining in the current time window."
      },
      "RateLimit-Reset": {
        "schema": { "type": "integer" },
        "description": "The number of seconds until the rate limit window resets."
      },
      "Retry-After": {
        "schema": { "type": "integer" },
        "description": "The number of seconds to wait before retrying after a 429 response."
      },
      "Sunset": {
        "schema": { "type": "string", "format": "date-time" },
        "description": "Date when the deprecated endpoint will be decommissioned (RFC 8594)."
      },
      "Deprecation": {
        "schema": { "type": "string" },
        "description": "Indicates the endpoint is deprecated and signals succession (draft-ietf-httpapi-deprecation-header)."
      }
    },
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 9457 Problem Details for HTTP APIs",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "A URI reference that identifies the problem type.",
            "example": "https://brante.dev/errors/invalid-parameter"
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type.",
            "example": "Invalid Parameter"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code generated by the origin server.",
            "example": 400
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence of the problem.",
            "example": "The 'url' parameter must be a valid HTTP or HTTPS URL."
          },
          "instance": {
            "type": "string",
            "format": "uri",
            "description": "A URI reference that identifies the specific occurrence of the problem."
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code.",
            "example": "ERR_INVALID_URL"
          }
        },
        "required": ["type", "title", "status", "detail"]
      },
      "HealthResponse": {
        "type": "object",
        "description": "Operational health payload",
        "properties": {
          "status": { "type": "string", "example": "ok", "description": "Service health indicator" },
          "version": { "type": "string", "example": "1.0.0", "description": "Deployed API version" },
          "service": { "type": "string", "example": "brante-dev-api-v1", "description": "Service name identifier" },
          "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 current timestamp" },
          "uptimeSeconds": { "type": "number", "example": 86400, "description": "Uptime in seconds" }
        },
        "required": ["status", "version", "timestamp"]
      },
      "DiagnosticRequest": {
        "type": "object",
        "description": "Target website diagnostic payload",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Target website URL to analyze (must be publicly reachable).",
            "example": "https://ejemplo.cl"
          }
        },
        "required": ["url"]
      },
      "DiagnosticResponse": {
        "type": "object",
        "description": "Diagnostic evaluation results",
        "properties": {
          "url": { "type": "string", "format": "uri", "example": "https://ejemplo.cl", "description": "Evaluated URL" },
          "score": { "type": "integer", "minimum": 0, "maximum": 100, "example": 94, "description": "Core Web Vitals overall score (0-100)" },
          "lcp": { "type": "string", "example": "1.2s", "description": "Largest Contentful Paint metric" },
          "cls": { "type": "string", "example": "0.02", "description": "Cumulative Layout Shift metric" },
          "inp": { "type": "string", "example": "48ms", "description": "Interaction to Next Paint metric" },
          "status": { "type": "string", "example": "optimized", "description": "Performance classification" },
          "auditTimestamp": { "type": "string", "format": "date-time", "description": "Audit generation timestamp" },
          "recommendations": {
            "type": "array",
            "description": "List of prioritized technical WPO recommendations",
            "items": { "type": "string" },
            "example": [
              "Enable AVIF/WebP image formatting to save ~450KB",
              "Implement Critical CSS inline to eliminate render-blocking delay"
            ]
          },
          "certifiedBy": { "type": "string", "example": "Benjamín Brante — brante.dev", "description": "Auditor verification signature" }
        },
        "required": ["url", "score", "recommendations"]
      },
      "DiagnosticProbeResponse": {
        "type": "object",
        "description": "Diagnostic engine probe and capabilities metadata",
        "properties": {
          "service": { "type": "string", "example": "brante-wpo-diagnostic", "description": "Diagnostic service name" },
          "version": { "type": "string", "example": "1.0.0", "description": "Engine version" },
          "freeTierAvailable": { "type": "boolean", "example": true, "description": "Whether zero-auth free sandbox is available" },
          "paymentProtocol": { "type": "string", "example": "x402", "description": "Supported micropayment protocol" },
          "description": { "type": "string", "description": "Service capabilities description" }
        },
        "required": ["service", "version", "freeTierAvailable"]
      },
      "PaymentFacilitatorResponse": {
        "type": "object",
        "description": "Payment facilitator parameters",
        "properties": {
          "protocol": { "type": "string", "example": "x402", "description": "Payment protocol identifier" },
          "version": { "type": "string", "example": "1.0.0", "description": "Protocol version" },
          "facilitatorUrl": { "type": "string", "format": "uri", "example": "https://x402.org/facilitator", "description": "Payment facilitator URL" },
          "walletAddress": { "type": "string", "example": "0x1111111111111111111111111111111111111111", "description": "Target settlement wallet address" },
          "currencies": {
            "type": "array",
            "description": "Supported currencies",
            "items": { "type": "string" },
            "example": ["USD", "CLP"]
          }
        },
        "required": ["protocol", "version", "facilitatorUrl"]
      }
    },
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 authorization server metadata at /.well-known/oauth-authorization-server",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://brante.dev/oauth/token",
            "scopes": {
              "read:audit": "Access public website diagnostics",
              "execute:wpo": "Execute automated performance optimizations",
              "contact:send": "Send inquiries directly to Benjamín Brante"
            }
          }
        }
      },
      "x402": {
        "type": "apiKey",
        "name": "X-402-Payment",
        "in": "header",
        "description": "x402 HTTP payment authorization token for micropayments"
      }
    }
  }
}