{
  "openapi": "3.1.0",
  "info": {
    "title": "Renovativ API",
    "description": "AI-powered building renovation planning and energy audit platform API. Upload building documents, check compliance, and analyze energy performance.",
    "version": "1.0.0",
    "contact": {
      "name": "Renovativ API Support",
      "email": "api@renovativ.ai",
      "url": "https://renovativ.ai/docs"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://api.renovativ.ai",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/upload": {
      "post": {
        "operationId": "uploadDocument",
        "summary": "Upload a building document",
        "description": "Upload a PDF document for AI analysis. The document is processed and stored in Google Drive organized by email. Returns file metadata including a viewable link.",
        "tags": ["Documents"],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "pdf": {
                    "type": "string",
                    "format": "binary",
                    "description": "PDF file to upload. Max 10MB."
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "User email address for organization and notifications"
                  },
                  "name": {
                    "type": "string",
                    "description": "User name (optional)"
                  },
                  "organization": {
                    "type": "string",
                    "description": "Organization name (optional)"
                  }
                },
                "required": ["pdf", "email"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "File uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadSuccess"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/test-upload": {
      "post": {
        "operationId": "testUpload",
        "summary": "Test folder creation",
        "description": "Test the folder creation logic without uploading a file. Useful for verifying Google Drive integration and authentication before uploading real documents.",
        "tags": ["Documents"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "User email address"
                  }
                },
                "required": ["email"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Folder created or found successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestUploadSuccess"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Health check",
        "description": "Check the API health status. Returns OK when the service is operational, along with the current timestamp and server version.",
        "tags": ["System"],
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatus"
                }
              }
            }
          }
        }
      }
    },
    "/api/events": {
      "get": {
        "operationId": "subscribeToEvents",
        "summary": "Subscribe to server events",
        "description": "SSE (Server-Sent Events) endpoint for real-time event streaming. Subscribe to receive updates about document processing, compliance checks, and system events. Connection sends heartbeats every 30 seconds and status updates every 60 seconds.",
        "tags": ["Events"],
        "responses": {
          "200": {
            "description": "SSE stream established",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/webhooks": {
      "post": {
        "operationId": "registerWebhook",
        "summary": "Register a webhook",
        "description": "Register a webhook URL to receive event notifications. Supports document.processed, compliance.completed, and upload.failed events. Optional secret for HMAC-SHA256 signature verification.",
        "tags": ["Webhooks"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Webhook URL to receive notifications"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": ["document.processed", "compliance.completed", "upload.failed"]
                    },
                    "description": "Events to subscribe to"
                  },
                  "secret": {
                    "type": "string",
                    "description": "Secret for webhook signature verification"
                  }
                },
                "required": ["url", "events"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "url": { "type": "string" },
                    "events": { "type": "array", "items": { "type": "string" } },
                    "created_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UploadSuccess": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "message": { "type": "string", "example": "File uploaded successfully" },
          "data": {
            "type": "object",
            "properties": {
              "fileId": { "type": "string", "example": "123456789" },
              "fileName": { "type": "string", "example": "building-plans_2026-04-18_143052.pdf" },
              "folderName": { "type": "string", "example": "user@example.com" },
              "viewLink": { "type": "string", "format": "uri", "example": "https://drive.google.com/..." }
            }
          }
        }
      },
      "TestUploadSuccess": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "message": { "type": "string", "example": "Folder created/found successfully" },
          "data": {
            "type": "object",
            "properties": {
              "folderName": { "type": "string" },
              "folderId": { "type": "string" }
            }
          }
        }
      },
      "HealthStatus": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "OK" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["success", "error", "error_code"],
        "properties": {
          "success": { "type": "boolean", "example": false, "description": "Always false for error responses" },
          "error": { "type": "string", "example": "Email is required", "description": "Human-readable error message" },
          "error_code": { "type": "string", "example": "MISSING_EMAIL", "description": "Machine-readable error code for programmatic handling" },
          "details": { "type": "string", "nullable": true, "description": "Additional context about the error" },
          "retry_after": { "type": "integer", "example": 60, "description": "Seconds to wait before retrying (for rate limit errors)" }
        }
      }
    }
  }
}