{
  "openapi": "3.1.0",
  "info": {
    "title": "WebEnture Public API",
    "version": "1.0.0",
    "description": "Supported Agency-plan API endpoints for website analysis and multi-agent audits. Unversioned /api/* routes are private application endpoints and are not part of this contract."
  },
  "servers": [
    {
      "url": "https://www.webenture.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyHeader": []
    }
  ],
  "paths": {
    "/api/v1/analyze": {
      "post": {
        "operationId": "analyzeWebsite",
        "summary": "Run a quick website analysis",
        "description": "Fetches one public URL and returns a score plus core SEO and content signals.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnalyzeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Analysis completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyzeResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/audit": {
      "post": {
        "operationId": "auditWebsite",
        "summary": "Run a multi-agent website audit",
        "description": "Runs up to three supported analyzers against one public URL. Supported agent identifiers are technical-seo, security, and accessibility.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "description": "Target URL could not be fetched",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "WebEnture API key",
        "description": "Agency API key beginning with wbnt_."
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Agency API key beginning with wbnt_."
      }
    },
    "schemas": {
      "AnalyzeRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["url"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          }
        }
      },
      "AnalyzeResponse": {
        "type": "object",
        "required": ["url", "score", "status", "loadTimeMs", "title", "seo", "content", "analyzedAt"],
        "properties": {
          "url": { "type": "string", "format": "uri" },
          "score": { "type": "integer", "minimum": 0, "maximum": 100 },
          "status": { "type": "integer" },
          "loadTimeMs": { "type": "integer", "minimum": 0 },
          "title": { "type": "string" },
          "metaDescription": { "type": ["string", "null"] },
          "seo": { "type": "object", "additionalProperties": true },
          "content": { "type": "object", "additionalProperties": true },
          "analyzedAt": { "type": "string", "format": "date-time" }
        }
      },
      "AuditRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["url"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          },
          "agents": {
            "type": "array",
            "minItems": 1,
            "maxItems": 3,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": ["technical-seo", "security", "accessibility"]
            },
            "default": ["technical-seo", "security", "accessibility"]
          },
          "budgets": {
            "type": "object",
            "description": "Optional CI gate thresholds. When supplied, the response includes a machine-readable gate result.",
            "additionalProperties": true,
            "properties": {
              "minScore": { "type": "number", "minimum": 0, "maximum": 100 },
              "maxIssues": { "type": "integer", "minimum": 0 },
              "perAgentMinScore": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 } },
              "perAgentMaxIssues": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }
            }
          }
        }
      },
      "AuditScore": {
        "type": "object",
        "required": ["score", "grade", "issueCount"],
        "properties": {
          "score": { "type": "number", "minimum": 0, "maximum": 100 },
          "grade": { "type": "string", "enum": ["A", "B", "C", "D", "F"] },
          "issueCount": { "type": "integer", "minimum": 0 }
        }
      },
      "AuditResponse": {
        "type": "object",
        "required": ["url", "timestamp", "agentsRun", "scores", "details"],
        "properties": {
          "url": { "type": "string", "format": "uri" },
          "timestamp": { "type": "string", "format": "date-time" },
          "agentsRun": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["technical-seo", "security", "accessibility"]
            }
          },
          "scores": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/AuditScore"
            }
          },
          "gate": {
            "$ref": "#/components/schemas/GateResult"
          },
          "details": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "GateResult": {
        "type": "object",
        "required": ["passed", "checked", "breaches"],
        "properties": {
          "passed": { "type": "boolean" },
          "checked": { "type": "integer", "minimum": 0 },
          "breaches": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["rule", "threshold", "actual", "message"],
              "properties": {
                "rule": { "type": "string" },
                "threshold": { "type": "number" },
                "actual": { "type": ["number", "null"] },
                "message": { "type": "string" }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" },
          "docs": { "type": "string", "format": "uri" },
          "resetInSeconds": { "type": "integer", "minimum": 0 }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "API key lacks permission or the owner does not have an active Agency plan",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded. Honor the Retry-After response header.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until another request may be attempted."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerError": {
        "description": "Analysis failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}