{
  "openapi": "3.1.0",
  "info": {
    "title": "CoolerFridges Public API",
    "version": "1.0.0",
    "description": "Public HTTP API for AI agents and integrators. All endpoints return JSON. Unauthenticated reads are free; quote submission is rate-limited. CoolerFridges (Foshan Jinglong Controller Co., Ltd.) is a source factory for integrated under-sink water systems (hot, cold, sparkling CO₂, filtered).",
    "contact": {
      "name": "CoolerFridges Sales Engineering",
      "email": "info@coolerfridges.com",
      "url": "https://coolerfridges.com/en/contact"
    },
    "license": {
      "name": "CoolerFridges Public API Terms",
      "url": "https://coolerfridges.com/en/terms"
    }
  },
  "servers": [
    {
      "url": "https://coolerfridges.com",
      "description": "Production"
    }
  ],
  "tags": [
    {"name": "Products", "description": "Catalog lookup and comparison"},
    {"name": "Applications", "description": "Use-case recommendations"},
    {"name": "Company", "description": "Company factsheet and capabilities"},
    {"name": "Quotes", "description": "Submit B2B quote requests"},
    {"name": "Social Proof", "description": "Customer testimonials and gallery"},
    {"name": "Knowledge", "description": "FAQ knowledge base"},
    {"name": "Discovery", "description": "Self-describing metadata"}
  ],
  "paths": {
    "/.well-known/agent.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Agent capability descriptor (Anthropic-style AgentCard)",
        "description": "Returns machine-readable description of this site's capabilities for AI agents. Includes tools, auth requirements, rate limits, and recommended query flow.",
        "operationId": "getAgentManifest",
        "responses": {
          "200": {
            "description": "Agent manifest",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentManifest"}}}
          }
        }
      }
    },
    "/.well-known/api.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "API discovery manifest",
        "description": "Lists all public API endpoints, their auth requirements, rate limits, and example use cases.",
        "operationId": "getApiDiscovery",
        "responses": {
          "200": {
            "description": "API discovery",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiDiscovery"}}}
          }
        }
      }
    },
    "/api/v1/openapi.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "OpenAPI 3.1 spec (this document)",
        "description": "Returns the full OpenAPI specification for programmatic consumption.",
        "operationId": "getOpenApiSpec",
        "responses": {
          "200": {
            "description": "OpenAPI spec",
            "content": {"application/json": {"schema": {"type": "object"}}}
          }
        }
      }
    },
    "/api/v1/factsheet": {
      "get": {
        "tags": ["Company"],
        "summary": "Company factsheet (structured)",
        "description": "Returns a structured company factsheet with founding year, certifications, factory capacity, geographic service areas, and product portfolio summary. Same data as llms.txt but in JSON for direct agent consumption.",
        "operationId": "getFactsheet",
        "responses": {
          "200": {
            "description": "Factsheet",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Factsheet"}}}
          }
        }
      }
    },
    "/api/v1/products": {
      "get": {
        "tags": ["Products"],
        "summary": "List and search the product catalog",
        "description": "Returns the CoolerFridges product catalog. Supports filtering by category, capacity range, voltage, and keyword. Results are paginated.",
        "operationId": "listProducts",
        "parameters": [
          {"$ref": "#/components/parameters/CategoryParam"},
          {"$ref": "#/components/parameters/CapacityMinParam"},
          {"$ref": "#/components/parameters/CapacityMaxParam"},
          {"$ref": "#/components/parameters/VoltageParam"},
          {"$ref": "#/components/parameters/KeywordParam"},
          {"$ref": "#/components/parameters/LocaleParam"},
          {"$ref": "#/components/parameters/LimitParam"},
          {"$ref": "#/components/parameters/OffsetParam"}
        ],
        "responses": {
          "200": {
            "description": "Product list",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProductList"}}}
          },
          "429": {"$ref": "#/components/responses/RateLimit"}
        }
      }
    },
    "/api/v1/products/{model}": {
      "get": {
        "tags": ["Products"],
        "summary": "Get a single product by model code",
        "operationId": "getProduct",
        "parameters": [
          {"name": "model", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Product model code (e.g. 'SYJ-F-C-001')"}
        ],
        "responses": {
          "200": {
            "description": "Product details",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Product"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"}
        }
      }
    },
    "/api/v1/products/compare": {
      "post": {
        "tags": ["Products"],
        "summary": "Compare 2-4 products side by side",
        "operationId": "compareProducts",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CompareRequest"}}}
        },
        "responses": {
          "200": {
            "description": "Comparison result",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ComparisonResult"}}}
          }
        }
      }
    },
    "/api/v1/applications": {
      "get": {
        "tags": ["Applications"],
        "summary": "List application scenarios and recommended products",
        "description": "Returns scenarios (hotel, office, healthcare, restaurant, OEM, retail, education, etc.) with the recommended product families and key decision factors for each.",
        "operationId": "listApplications",
        "parameters": [
          {"name": "scenario", "in": "query", "schema": {"type": "string", "enum": ["hotel", "office", "healthcare", "restaurant", "oem", "retail", "education", "home", "apartment", "coffee", "vending"]}, "description": "Filter by scenario"},
          {"name": "people_count", "in": "query", "schema": {"type": "integer"}, "description": "Estimated people served per day"},
          {"$ref": "#/components/parameters/LocaleParam"}
        ],
        "responses": {
          "200": {
            "description": "Application list",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApplicationList"}}}
          }
        }
      }
    },
    "/api/v1/quotes": {
      "post": {
        "tags": ["Quotes"],
        "summary": "Submit a B2B quote request",
        "description": "Submit a B2B quote / RFQ. Required: company name, contact email, application, target capacity, destination country. Optional: voltage, branding needs, sample requirements, notes. CoolerFridges sales team responds within 24 hours on business days.",
        "operationId": "createQuote",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/QuoteRequest"}}}
        },
        "responses": {
          "201": {
            "description": "Quote request submitted",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/QuoteResponse"}}}
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "429": {"$ref": "#/components/responses/RateLimit"}
        }
      }
    },
    "/api/v1/testimonials": {
      "get": {
        "tags": ["Social Proof"],
        "summary": "List customer testimonials",
        "operationId": "listTestimonials",
        "parameters": [
          {"name": "region", "in": "query", "schema": {"type": "string"}, "description": "Filter by region (e.g. 'AU', 'EU', 'US')"},
          {"name": "use_case", "in": "query", "schema": {"type": "string"}, "description": "Filter by use case (hotel, office, healthcare, etc.)"},
          {"$ref": "#/components/parameters/LocaleParam"},
          {"$ref": "#/components/parameters/LimitParam"}
        ],
        "responses": {
          "200": {
            "description": "Testimonial list",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TestimonialList"}}}
          }
        }
      }
    },
    "/api/v1/gallery": {
      "get": {
        "tags": ["Social Proof"],
        "summary": "List gallery images (factory, OEM products, real deployments)",
        "operationId": "listGallery",
        "parameters": [
          {"name": "category", "in": "query", "schema": {"type": "string", "enum": ["factory", "oem", "installation", "lifestyle"]}},
          {"$ref": "#/components/parameters/LimitParam"}
        ],
        "responses": {
          "200": {
            "description": "Gallery image list",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GalleryList"}}}
          }
        }
      }
    },
    "/api/v1/faqs": {
      "get": {
        "tags": ["Knowledge"],
        "summary": "FAQ knowledge base",
        "description": "Returns canonical Q&As that customers ask before purchasing. Designed so AI agents can quote CoolerFridges' own expertise in their own answers without hallucinating.",
        "operationId": "listFaqs",
        "parameters": [
          {"name": "topic", "in": "query", "schema": {"type": "string"}, "description": "Filter by topic (oem, certification, capacity, etc.)"},
          {"$ref": "#/components/parameters/LocaleParam"}
        ],
        "responses": {
          "200": {
            "description": "FAQ list",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/FaqList"}}}
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "CategoryParam": {"name": "category", "in": "query", "schema": {"type": "string"}, "description": "Product category: 'chiller', 'soda-system', 'multi-function', 'commercial', 'instant-hot', 'accessory'"},
      "CapacityMinParam": {"name": "capacity_min", "in": "query", "schema": {"type": "number"}, "description": "Minimum cooling capacity in L/h"},
      "CapacityMaxParam": {"name": "capacity_max", "in": "query", "schema": {"type": "number"}, "description": "Maximum cooling capacity in L/h"},
      "VoltageParam": {"name": "voltage", "in": "query", "schema": {"type": "string"}, "description": "Voltage (110V or 220V)"},
      "KeywordParam": {"name": "keyword", "in": "query", "schema": {"type": "string"}, "description": "Keyword search across product name, sales pitch, and selling points"},
      "LocaleParam": {"name": "locale", "in": "query", "schema": {"type": "string", "enum": ["en", "es", "fr", "de", "pt", "ar"], "default": "en"}},
      "LimitParam": {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 20, "maximum": 100}, "description": "Maximum number of results"},
      "OffsetParam": {"name": "offset", "in": "query", "schema": {"type": "integer", "default": 0}, "description": "Pagination offset"}
    },
    "responses": {
      "NotFound": {"description": "Resource not found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "BadRequest": {"description": "Invalid request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "RateLimit": {"description": "Rate limit exceeded", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {"type": "string"},
          "message": {"type": "string"}
        }
      },
      "AgentManifest": {"type": "object"},
      "ApiDiscovery": {"type": "object"},
      "Factsheet": {
        "type": "object",
        "properties": {
          "company_name": {"type": "string", "example": "Foshan Jinglong Controller Co., Ltd."},
          "brand": {"type": "string", "example": "CoolerFridges"},
          "founded_year": {"type": "integer", "example": 2014},
          "country": {"type": "string", "example": "China"},
          "city": {"type": "string", "example": "Foshan"},
          "region": {"type": "string", "example": "Guangdong"},
          "certifications": {"type": "array", "items": {"type": "string"}, "example": ["CE", "RoHS", "CB"]},
          "service_regions": {"type": "array", "items": {"type": "string"}},
          "languages": {"type": "array", "items": {"type": "string"}, "example": ["en", "es", "fr", "de", "pt", "ar"]},
          "product_portfolio": {"type": "object"},
          "differentiators": {"type": "array", "items": {"type": "string"}}
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "model": {"type": "string", "example": "SYJ-F-C-001"},
          "name": {"type": "string"},
          "category": {"type": "string"},
          "image_url": {"type": "string"},
          "specs": {"type": "object", "additionalProperties": {"type": "string"}},
          "sales_pitch": {"type": "string"},
          "selling_points": {"type": "array", "items": {"type": "string"}},
          "faq": {"type": "array", "items": {"type": "object", "properties": {"q": {"type": "string"}, "a": {"type": "string"}}}},
          "country_of_origin": {"type": "string"},
          "certifications": {"type": "array", "items": {"type": "string"}},
          "url": {"type": "string"}
        }
      },
      "ProductList": {
        "type": "object",
        "properties": {
          "total": {"type": "integer"},
          "limit": {"type": "integer"},
          "offset": {"type": "integer"},
          "products": {"type": "array", "items": {"$ref": "#/components/schemas/Product"}}
        }
      },
      "CompareRequest": {
        "type": "object",
        "required": ["models"],
        "properties": {
          "models": {"type": "array", "items": {"type": "string"}, "minItems": 2, "maxItems": 4},
          "locale": {"type": "string", "default": "en"}
        }
      },
      "ComparisonResult": {
        "type": "object",
        "properties": {
          "products": {"type": "array", "items": {"$ref": "#/components/schemas/Product"}},
          "differences": {"type": "object"},
          "recommendation": {"type": "string"}
        }
      },
      "ApplicationList": {
        "type": "object",
        "properties": {
          "applications": {"type": "array", "items": {"type": "object"}}
        }
      },
      "QuoteRequest": {
        "type": "object",
        "required": ["company_name", "contact_email", "application", "destination_country"],
        "properties": {
          "company_name": {"type": "string"},
          "contact_email": {"type": "string", "format": "email"},
          "contact_name": {"type": "string"},
          "contact_phone": {"type": "string"},
          "application": {"type": "string", "description": "One of: hotel, office, restaurant, healthcare, home, oem, retail, education, etc."},
          "target_capacity_lph": {"type": "number"},
          "voltage": {"type": "string"},
          "destination_country": {"type": "string"},
          "branding_requirements": {"type": "string", "description": "OEM/ODM requirements"},
          "sample_required": {"type": "boolean"},
          "notes": {"type": "string"},
          "source": {"type": "string", "description": "Where this lead came from (e.g. 'AI Agent: Claude')"}
        }
      },
      "QuoteResponse": {
        "type": "object",
        "properties": {
          "quote_id": {"type": "string", "format": "uuid"},
          "status": {"type": "string", "example": "received"},
          "sla": {"type": "string", "example": "24 hours"},
          "expected_response_channel": {"type": "string", "example": "email"},
          "tracking_url": {"type": "string"}
        }
      },
      "TestimonialList": {
        "type": "object",
        "properties": {
          "testimonials": {"type": "array", "items": {"type": "object"}}
        }
      },
      "GalleryList": {
        "type": "object",
        "properties": {
          "images": {"type": "array", "items": {"type": "object"}}
        }
      },
      "FaqList": {
        "type": "object",
        "properties": {
          "faqs": {"type": "array", "items": {"type": "object", "properties": {"topic": {"type": "string"}, "q": {"type": "string"}, "a": {"type": "string"}, "locale": {"type": "string"}}}}
        }
      }
    }
  }
}