{
  "openapi": "3.1.0",
  "info": {
    "title": "WP Scanner API",
    "version": "1.0.0",
    "description": "Public API for WP Scanner analysis platform."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "components": {
    "schemas": {
      "AnalysisSummary": {
        "type": "object",
        "properties": {
          "overallScore": {
            "type": "integer"
          },
          "verdict": {
            "type": "string",
            "enum": [
              "good",
              "improvable",
              "poor"
            ]
          },
          "sections": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "enum": [
                "good",
                "improvable",
                "poor"
              ]
            }
          },
          "sectionScores": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "wordpressCompletenessScore": {
            "type": "integer"
          },
          "privacyScore": {
            "type": "integer"
          },
          "pluginCount": {
            "type": "integer"
          },
          "themeCount": {
            "type": "integer"
          },
          "vulnerabilitiesCount": {
            "type": "integer"
          },
          "toolsCount": {
            "type": "integer"
          },
          "accessibilityViolations": {
            "type": "integer"
          },
          "findingsBuckets": {
            "type": "object",
            "properties": {
              "info": {
                "type": "integer"
              },
              "low": {
                "type": "integer"
              },
              "medium": {
                "type": "integer"
              },
              "high": {
                "type": "integer"
              },
              "critical": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              }
            },
            "required": [
              "info",
              "low",
              "medium",
              "high",
              "critical",
              "total"
            ]
          },
          "executiveSummary": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "topRecommendations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "severity": {
                  "type": "string",
                  "enum": [
                    "info",
                    "low",
                    "medium",
                    "high",
                    "critical"
                  ]
                }
              },
              "required": [
                "id",
                "title",
                "severity"
              ]
            }
          },
          "generatedAt": {
            "type": "string"
          }
        },
        "required": [
          "overallScore",
          "verdict",
          "sections",
          "pluginCount",
          "themeCount",
          "vulnerabilitiesCount",
          "toolsCount",
          "accessibilityViolations",
          "generatedAt"
        ]
      },
      "Analysis": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "$ref": "#/components/schemas/AnalysisStatus"
          },
          "url": {
            "type": "string"
          },
          "normalizedUrl": {
            "type": "string"
          },
          "createdAt": {
            "type": "string"
          },
          "startedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "finishedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "ownerId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "source": {
            "type": "string"
          },
          "summary": {
            "$ref": "#/components/schemas/AnalysisSummary"
          }
        },
        "required": [
          "id",
          "status",
          "url",
          "normalizedUrl",
          "createdAt"
        ]
      },
      "AnalysisStatus": {
        "type": "string",
        "enum": [
          "pending",
          "running",
          "completed",
          "failed"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/api/v1/analyses": {
      "post": {
        "summary": "Create an analysis job",
        "tags": [
          "Analyses"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 2048
                  },
                  "source": {
                    "type": "string",
                    "maxLength": 32
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Analysis accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Analysis"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "requestId": {
                          "type": "string"
                        },
                        "pagination": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "nextCursor": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "total": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "limit"
                          ]
                        },
                        "rateLimit": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "remaining": {
                              "type": "integer"
                            },
                            "resetInSeconds": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "limit",
                            "remaining",
                            "resetInSeconds"
                          ]
                        }
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {}
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {}
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {}
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List analyses owned by the authenticated principal",
        "tags": [
          "Analyses"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "running",
                "completed",
                "failed"
              ]
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List of analyses",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Analysis"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "requestId": {
                          "type": "string"
                        },
                        "pagination": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "nextCursor": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "total": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "limit"
                          ]
                        },
                        "rateLimit": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "remaining": {
                              "type": "integer"
                            },
                            "resetInSeconds": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "limit",
                            "remaining",
                            "resetInSeconds"
                          ]
                        }
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {}
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/analyses/{id}": {
      "get": {
        "summary": "Fetch analysis status + summary",
        "tags": [
          "Analyses"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Analysis details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Analysis"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "requestId": {
                          "type": "string"
                        },
                        "pagination": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "nextCursor": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "total": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "limit"
                          ]
                        },
                        "rateLimit": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "remaining": {
                              "type": "integer"
                            },
                            "resetInSeconds": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "limit",
                            "remaining",
                            "resetInSeconds"
                          ]
                        }
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {}
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/analyses/{id}/result": {
      "get": {
        "summary": "Fetch the full analysis result",
        "tags": [
          "Analyses"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Full analysis report",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "analysis": {
                          "$ref": "#/components/schemas/Analysis"
                        },
                        "result": {},
                        "summary": {
                          "$ref": "#/components/schemas/AnalysisSummary"
                        }
                      },
                      "required": [
                        "analysis",
                        "summary"
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "requestId": {
                          "type": "string"
                        },
                        "pagination": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "nextCursor": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "total": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "limit"
                          ]
                        },
                        "rateLimit": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "remaining": {
                              "type": "integer"
                            },
                            "resetInSeconds": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "limit",
                            "remaining",
                            "resetInSeconds"
                          ]
                        }
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Analysis not completed yet",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {}
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/analyses/compare": {
      "get": {
        "summary": "Compare two completed analyses",
        "tags": [
          "Analyses"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true,
            "name": "a",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true,
            "name": "b",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Structured diff between two analyses",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {},
                    "meta": {
                      "type": "object",
                      "properties": {
                        "requestId": {
                          "type": "string"
                        },
                        "pagination": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "nextCursor": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "total": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "limit"
                          ]
                        },
                        "rateLimit": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "remaining": {
                              "type": "integer"
                            },
                            "resetInSeconds": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "limit",
                            "remaining",
                            "resetInSeconds"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "One of the analyses is not ready",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {}
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/analyses/{id}/export": {
      "get": {
        "summary": "Export a report as HTML or PDF",
        "tags": [
          "Analyses"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true,
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "html",
                "pdf"
              ]
            },
            "required": true,
            "name": "format",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Binary report payload",
            "content": {
              "application/pdf": {
                "schema": {}
              },
              "text/html": {
                "schema": {}
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {}
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/api-keys": {
      "post": {
        "summary": "Create an API key (session auth required)",
        "tags": [
          "API Keys"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "analyses:read",
                        "analyses:write"
                      ]
                    },
                    "minItems": 1
                  },
                  "rateLimitPerMin": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 600
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created (plainText shown only once)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "plainText": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "plainText"
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "requestId": {
                          "type": "string"
                        },
                        "pagination": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "nextCursor": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "total": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "limit"
                          ]
                        },
                        "rateLimit": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "remaining": {
                              "type": "integer"
                            },
                            "resetInSeconds": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "limit",
                            "remaining",
                            "resetInSeconds"
                          ]
                        }
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {}
}