{
  "openapi": "3.1.0",
  "info": {
    "title": "Luméa Capital Real Estate Public & Agent API",
    "description": "Official REST API v1, lead ingestion, and real estate agency partner integration for Luméa Capital (San Luis Potosí, México). Developers and autonomous AI agents can interact using standard HTTP/cURL requests with JSON payloads or Markdown content negotiation.",
    "version": "1.0.0",
    "x-deprecation-policy": "Luméa Capital API follows semantic lifecycle versioning. When endpoints are updated, backward compatibility is maintained under /v1/. Deprecated endpoints will include Deprecation and Sunset HTTP headers with at least 6 months advance notice.",
    "contact": {
      "name": "Luméa Capital Real Estate Engineering",
      "email": "contacto@lumeacapital.mx",
      "url": "https://lumeacapital.mx/developers"
    }
  },
  "servers": [
    {
      "url": "https://lumeacapital.mx",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/v1/contact": {
      "post": {
        "summary": "Submit a buyer lead inquiry or schedule property inspection (v1)",
        "description": "Captures customer interest for a specific property or general luxury real estate advisory in San Luis Potosí.",
        "operationId": "submitContactInquiryV1",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactInquiryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inquiry successfully recorded",
            "headers": {
              "RateLimit-Limit": { "schema": { "type": "string" }, "description": "Maximum requests allowed in window" },
              "RateLimit-Remaining": { "schema": { "type": "string" }, "description": "Remaining requests in window" },
              "RateLimit-Reset": { "schema": { "type": "string" }, "description": "Seconds until window resets" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error in request payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StructuredErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StructuredErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "summary": "Submit a buyer lead inquiry (Canonical alias)",
        "description": "Canonical endpoint alias to /api/v1/contact.",
        "operationId": "submitContactInquiryCanonical",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactInquiryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inquiry successfully recorded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StructuredErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/partner-waitlist": {
      "post": {
        "summary": "Submit real estate agency application to Partner Fundador network (v1)",
        "description": "Registers an agency or certified broker to access Luméa's partner inventory portal.",
        "operationId": "submitPartnerApplicationV1",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerWaitlistRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application recorded with referral code assigned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerWaitlistResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid payload or unverified referral code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StructuredErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/partner-waitlist": {
      "post": {
        "summary": "Submit agency application (Canonical alias)",
        "description": "Canonical endpoint alias to /api/v1/partner-waitlist.",
        "operationId": "submitPartnerApplicationCanonical",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerWaitlistRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application recorded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerWaitlistResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/assessment-email": {
      "post": {
        "summary": "Send purchase capacity assessment summary to client (v1)",
        "description": "Emails calculated buying capacity and matching property recommendations to the client.",
        "operationId": "sendAssessmentEmailV1",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssessmentEmailRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Assessment email successfully queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardSuccessResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ContactInquiryRequest": {
        "type": "object",
        "required": ["name", "phone", "email", "message"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Full name of the client"
          },
          "phone": {
            "type": "string",
            "description": "Phone number or WhatsApp (preferably with country code)"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Client email address"
          },
          "message": {
            "type": "string",
            "description": "Inquiry message or tour request details"
          },
          "propertyId": {
            "type": "string",
            "description": "Optional slug or UUID of the property of interest (e.g. 'torre-utente')"
          },
          "origin": {
            "type": "string",
            "description": "Source of lead (e.g. 'ai_agent', 'curl_cli', 'portal')"
          }
        }
      },
      "PartnerWaitlistRequest": {
        "type": "object",
        "required": ["agencyName", "contactName", "email", "phone", "city"],
        "properties": {
          "agencyName": {
            "type": "string",
            "description": "Legal or trade name of the real estate agency"
          },
          "contactName": {
            "type": "string",
            "description": "Name of director or principal broker"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "phone": {
            "type": "string"
          },
          "city": {
            "type": "string",
            "description": "City of operation (e.g. 'San Luis Potosí')"
          },
          "primaryInterest": {
            "type": "string",
            "description": "Comma-separated list of interests ('inventory,team,prospects')"
          },
          "referredByCode": {
            "type": "string",
            "description": "Optional referral code formatted as LP-XXXXX"
          }
        }
      },
      "AssessmentEmailRequest": {
        "type": "object",
        "required": ["email", "name", "budget"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "name": { "type": "string" },
          "budget": { "type": "number" },
          "downPayment": { "type": "number" },
          "monthlyCapacity": { "type": "number" }
        }
      },
      "StandardSuccessResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "message": { "type": "string", "example": "Solicitud procesada correctamente" }
        }
      },
      "PartnerWaitlistResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "waitlistId": { "type": "string", "format": "uuid" },
          "referralCode": { "type": "string", "example": "LP-K8M9Q" }
        }
      },
      "StructuredErrorResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string", "example": "NOT_FOUND" },
              "message": { "type": "string", "example": "El endpoint o recurso no existe." },
              "hint": { "type": "string", "example": "Consulte https://lumeacapital.mx/openapi.json para la lista completa de endpoints." }
            }
          }
        }
      }
    }
  }
}