{
  "openapi": "3.1.0",
  "info": {
    "title": "Laburen Public API",
    "version": "1.0.0",
    "summary": "Public lead-capture API for Laburen.com",
    "description": "Laburen.com builds AI Employees (Empleados IA) that automate sales, support and operations over WhatsApp and other channels for businesses in Latin America and Spain. This is the public HTTP API exposed by the marketing site (laburen.com), currently limited to lead capture. See https://laburen.com/developers for human-readable docs, https://laburen.com/agent.txt for AI agent usage guidance, and https://laburen.com/llms.txt for a full site index.",
    "contact": {
      "name": "Laburen.com",
      "url": "https://laburen.com/developers",
      "email": "soporte@laburen.com"
    },
    "license": {
      "name": "All rights reserved",
      "url": "https://laburen.com"
    }
  },
  "servers": [
    { "url": "https://laburen.com", "description": "Production" }
  ],
  "tags": [
    { "name": "Leads", "description": "Capturing sales and support leads from the marketing site." }
  ],
  "paths": {
    "/api/leads": {
      "post": {
        "operationId": "createLead",
        "summary": "Submit a lead",
        "description": "Creates a lead record (name, email and optional qualification data) collected from a form on laburen.com — the blog CTA, the ROI calculator, or the AI-readiness diagnostic. Rate limited to 5 requests per minute per IP address.",
        "tags": ["Leads"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateLeadRequest" },
              "examples": {
                "minimal": {
                  "summary": "Minimal valid request",
                  "value": { "name": "Ada Lovelace", "email": "ada@example.com" }
                },
                "full": {
                  "summary": "Request with qualification data",
                  "value": {
                    "name": "Ada Lovelace",
                    "email": "ada@example.com",
                    "phone": "+54 9 11 2345 6789",
                    "source": "roi-calculator-ecommerce",
                    "company": "Acme Corp",
                    "industry": "ecommerce",
                    "companySize": "11-50",
                    "score": 82,
                    "levelLabel": "Alto potencial",
                    "recommendedAgent": "AI Sales Employee"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lead created.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CreateLeadResponse" },
                "examples": {
                  "success": { "value": { "success": true, "id": "abc123" } }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: missing or malformed fields.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiError" },
                "examples": {
                  "missingFields": {
                    "value": {
                      "error": "Name and email are required",
                      "code": "validation_error",
                      "hint": "Include both \"name\" and \"email\" (non-empty strings) in the JSON body."
                    }
                  },
                  "invalidEmail": {
                    "value": {
                      "error": "Invalid email format",
                      "code": "validation_error",
                      "hint": "Provide a valid email address, e.g. \"name@example.com\"."
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. Only POST is supported on this endpoint.",
            "headers": {
              "Allow": { "schema": { "type": "string", "example": "POST" } }
            },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } }
            }
          },
          "429": {
            "description": "Rate limit exceeded (5 requests per minute per IP).",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } }
            }
          },
          "500": {
            "description": "Unexpected server error while saving the lead.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } }
            }
          }
        }
      }
    },
    "/api/{unknown}": {
      "get": {
        "operationId": "apiNotFound",
        "summary": "Any unrecognized API path",
        "description": "Every /api/* path that doesn't match a real endpoint returns a structured JSON 404 (not an HTML page), for every HTTP method.",
        "tags": ["Leads"],
        "parameters": [
          {
            "name": "unknown",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Any path segment that does not match a defined endpoint."
          }
        ],
        "responses": {
          "404": {
            "description": "No route matches the requested path.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateLeadRequest": {
        "type": "object",
        "required": ["name", "email"],
        "properties": {
          "name": { "type": "string", "maxLength": 100, "description": "Full name of the lead." },
          "email": { "type": "string", "format": "email", "maxLength": 254 },
          "phone": { "type": "string", "maxLength": 30, "description": "7-20 digits once non-digit characters are stripped." },
          "source": { "type": "string", "maxLength": 50, "description": "Origin of the lead, e.g. \"blog-cta\" or \"roi-calculator-ecommerce\"." },
          "postSlug": { "type": "string", "maxLength": 200, "description": "Blog post slug, when the lead came from a blog CTA." },
          "company": { "type": "string", "maxLength": 150 },
          "industry": { "type": "string", "maxLength": 60 },
          "companySize": { "type": "string", "maxLength": 40 },
          "area": { "type": "string", "maxLength": 60 },
          "hoursPerWeek": { "type": "string", "maxLength": 40 },
          "aiToday": { "type": "string", "maxLength": 80 },
          "score": { "type": "number", "minimum": 0, "maximum": 999, "description": "AI-readiness diagnostic score, clamped to 0-999." },
          "levelLabel": { "type": "string", "maxLength": 60 },
          "recommendedAgent": { "type": "string", "maxLength": 150 }
        }
      },
      "CreateLeadResponse": {
        "type": "object",
        "required": ["success", "id"],
        "properties": {
          "success": { "type": "boolean" },
          "id": { "type": "string", "description": "Sanity document id of the created lead." }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["error", "code", "hint"],
        "properties": {
          "error": { "type": "string", "description": "Human-readable error message." },
          "code": {
            "type": "string",
            "description": "Machine-readable error code.",
            "enum": [
              "validation_error",
              "invalid_json",
              "rate_limited",
              "method_not_allowed",
              "not_found",
              "internal_error"
            ]
          },
          "hint": { "type": "string", "description": "Suggested resolution for the error." }
        }
      }
    }
  }
}