{
  "openapi": "3.1.0",
  "info": {
    "title": "InquilinOS API",
    "version": "1.0.0",
    "description": "Real estate intelligence API for the Spanish market. Covers 6,686+ neighbourhoods across 45 cities with investment grading, lifestyle scores, pricing trends, and rental contract analysis.",
    "contact": { "email": "hello@inquilinos.app" },
    "license": { "name": "Proprietary" }
  },
  "servers": [
    { "url": "https://inquilinos.me", "description": "Production" }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "HMAC HS256 JWT. Obtain via POST /api/auth/password-login ({email,password}) or magic-link flow. Send as Authorization: Bearer <token> or as cookie __session. Tier (basic|pro|enterprise) is embedded in the token payload."
      }
    }
  },
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Health check",
        "description": "Returns API and database status.",
        "tags": ["System"],
        "responses": {
          "200": {
            "description": "Healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status":    { "type": "string", "enum": ["healthy", "unhealthy"] },
                    "db":        { "type": "string", "enum": ["connected", "disconnected"] },
                    "latencyMs": { "type": "integer" },
                    "version":   { "type": "string" }
                  }
                }
              }
            }
          },
          "503": { "description": "Unhealthy" }
        }
      }
    },
    "/api/neighbourhood": {
      "get": {
        "operationId": "getNeighbourhood",
        "summary": "Neighbourhood intelligence",
        "description": "Returns investment grade (A–D), gross yield, lifestyle scores, demographic data, and OSM amenity scores for a Spanish neighbourhood. Basic fields are public; full fields require a Pro or Enterprise JWT.",
        "tags": ["Analytics"],
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "City slug (e.g. madrid, barcelona, valencia)",
            "example": "madrid"
          },
          {
            "name": "neighbourhood",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Neighbourhood slug",
            "example": "malasana"
          }
        ],
        "security": [],
        "responses": {
          "200": { "description": "Neighbourhood data" },
          "404": { "description": "City or neighbourhood not found" }
        }
      }
    },
    "/api/rankings": {
      "get": {
        "operationId": "getRankings",
        "summary": "City neighbourhood rankings",
        "description": "Returns all neighbourhoods in a city sorted by investment grade, gross yield, or lifestyle score.",
        "tags": ["Analytics"],
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "example": "madrid"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["grade", "yield", "lifestyle"] },
            "description": "Sort key (default: grade)"
          }
        ],
        "security": [],
        "responses": {
          "200": { "description": "Ranked neighbourhood list" },
          "404": { "description": "City not found" }
        }
      }
    },
    "/api/trends": {
      "get": {
        "operationId": "getTrends",
        "summary": "Pricing trends",
        "description": "Quarterly sale and rent price indices for a city. Requires Pro tier.",
        "tags": ["Analytics"],
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "example": "barcelona"
          }
        ],
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Price trend series" },
          "403": { "description": "Insufficient tier" }
        }
      }
    },
    "/api/lau/scan": {
      "post": {
        "operationId": "scanContract",
        "summary": "Rental contract analysis (LAU)",
        "description": "Scans a Spanish rental contract for 19 critical legal violations and 6 alert types using regex rules. Max 120 KB input. Spanish-language contracts only. Requires Enterprise tier.",
        "tags": ["Legal"],
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": {
                    "type": "string",
                    "description": "Full plain text of the rental contract (max 120 KB)",
                    "maxLength": 122880
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Analysis results with violations and alerts" },
          "400": { "description": "Validation error (text too long or missing)" },
          "403": { "description": "Insufficient tier" }
        }
      }
    },
    "/api/irpf": {
      "post": {
        "operationId": "calculateIrpf",
        "summary": "IRPF tax calculator",
        "description": "Estimates Spanish income tax (IRPF) liability for a rental income scenario.",
        "tags": ["Tax"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Rental income scenario parameters"
              }
            }
          }
        },
        "responses": {
          "200": { "description": "IRPF calculation result" },
          "400": { "description": "Invalid input" }
        }
      }
    },
    "/api/cashflow": {
      "post": {
        "operationId": "calculateCashflow",
        "summary": "Net cashflow calculator",
        "description": "Projects net cashflow for a buy-to-let investment scenario, including taxes and expenses.",
        "tags": ["Investment"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Buy-to-let scenario parameters"
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Cashflow projection" },
          "400": { "description": "Invalid input" }
        }
      }
    }
  }
}