{
  "openapi": "3.1.0",
  "info": {
    "title": "LeaseGuru.ai Public Marketplace API",
    "version": "1.0.0",
    "description": "Public read-only endpoints for querying US car lease listings, LeaseGuru 1–100 deal scores, curated brand/model catalog rollups, and NHTSA VIN decoding.",
    "contact": {
      "name": "LeaseGuru.ai",
      "url": "https://leaseguru.ai/contact"
    }
  },
  "servers": [
    {
      "url": "https://leaseguru.ai",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/deals-page": {
      "get": {
        "operationId": "listLeaseDeals",
        "summary": "Query live car lease deals",
        "description": "Returns paginated, filterable car lease listings with LeaseGuru 1–100 value scores, monthly payment, due-at-signing, and term.",
        "parameters": [
          {
            "name": "make",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by vehicle brand/make (e.g. BMW, Toyota, Tesla)."
          },
          {
            "name": "model",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by vehicle model name."
          },
          {
            "name": "maxPayment",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Maximum monthly lease payment in USD."
          },
          {
            "name": "maxDriveOff",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Maximum due-at-signing amount in USD."
          },
          {
            "name": "sortBy",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "payment_asc",
                "driveoff_asc",
                "value_desc",
                "score_desc"
              ]
            },
            "description": "Sort order for returned lease deals."
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "1-indexed page number (48 deals per page)."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated lease deals response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deals": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "totalCount": {
                      "type": "integer"
                    },
                    "countCapped": {
                      "type": "boolean"
                    },
                    "page": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "deals",
                    "hasMore",
                    "totalCount",
                    "page"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/search-catalog": {
      "get": {
        "operationId": "getSearchCatalog",
        "summary": "Get active brand and model lease catalog rollup",
        "description": "Returns curated brands and models with active listing counts and lowest monthly payment.",
        "responses": {
          "200": {
            "description": "Brand and model catalog rollup",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "brands": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "models": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "brands",
                    "models"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/vin-decode": {
      "get": {
        "operationId": "decodeVin",
        "summary": "Decode a 11–17 character vehicle identification number (VIN)",
        "parameters": [
          {
            "name": "vin",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 11,
              "maxLength": 17
            },
            "description": "Vehicle Identification Number (VIN)."
          }
        ],
        "responses": {
          "200": {
            "description": "Decoded vehicle year, make, and model",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "vin": {
                      "type": "string"
                    },
                    "modelYear": {
                      "type": "string"
                    },
                    "make": {
                      "type": "string"
                    },
                    "model": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "vin"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealthStatus",
        "summary": "Service health check",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "service": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status",
                    "service"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}