{
  "openapi": "3.0.0",
  "info": {
    "title": "Bonizu Product Intelligence API",
    "description": "Semantic product search and comparison across beauty, personal care, supplements, vitamins, and wellness products. Benelux market focus. Exact category values are available via GET /categories or the list_categories MCP tool.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://bonizu.com/api"
    }
  ],
  "paths": {
    "/categories": {
      "get": {
        "operationId": "list_categories",
        "summary": "List available product categories",
        "description": "Returns distinct in-stock product categories with product counts, sorted by count descending. Use before search_bonizu_catalog when you need exact category filter values.",
        "responses": {
          "200": {
            "description": "Category inventory",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": ["category", "count"],
                    "properties": {
                      "category": {"type": "string"},
                      "count": {"type": "integer"}
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/search": {
      "post": {
        "operationId": "search_bonizu_catalog",
        "summary": "Search for products using natural language",
        "description": "Search products using semantic natural language queries across skincare, bodycare, hair care, supplements, vitamins & minerals, and wellness. Returns ranked results with match explanations. Understands user context like budget, routine, and constraints. Call GET /categories (or list_categories) for exact category filter values.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Natural language search query",
                    "example": "gentle cleanser for dry sensitive skin under 20 euro"
                  },
                  "filters": {
                    "type": "object",
                    "properties": {
                      "max_price": {"type": "number"},
                      "min_rating": {"type": "number"},
                      "in_stock": {"type": "boolean"},
                      "category": {
                        "type": "string",
                        "description": "Exact match against the canonical English category slug (e.g. 'skincare', 'hair-care', 'supplements'). Call GET /categories or the list_categories MCP tool for the current list of available values."
                      }
                    }
                  },
                  "limit": {
                    "type": "integer",
                    "default": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked product results with match explanations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {"type": "string"},
                          "title": {"type": "string"},
                          "brand": {"type": "string"},
                          "price_eur": {"type": "number"},
                          "rating": {"type": "number"},
                          "category": {"type": "string"},
                          "summary": {"type": "string"},
                          "highlights": {"type": "array", "items": {"type": "string"}},
                          "limitations": {"type": "array", "items": {"type": "string"}},
                          "affiliate_url": {"type": "string"},
                          "relevance_score": {"type": "number"},
                          "match_reason": {"type": "string"}
                        }
                      }
                    },
                    "total": {"type": "integer"}
                  }
                }
              }
            }
          }
        }
      }
    },
    "/compare": {
      "post": {
        "operationId": "compare_bonizu_products",
        "summary": "Compare multiple products side by side",
        "description": "Compare 2-4 products with scores per dimension and a recommendation based on user context.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["product_ids"],
                "properties": {
                  "product_ids": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "Array of product UUIDs to compare"
                  },
                  "context": {
                    "type": "string",
                    "description": "User context for personalized recommendation",
                    "example": "dry sensitive skin, fragrance-free preference"
                  },
                  "language": {
                    "type": "string",
                    "default": "nl"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Structured comparison with scores and recommendation"
          }
        }
      }
    }
  }
}