{
  "openapi": "3.1.0",
  "info": {
    "title": "SkinGuide API",
    "description": "Search skincare products by Baumann skin type, product category, budget, and more. Find the perfect products for your skin type among 16 different skin type profiles (ORPW, ORPT, ORNW, ORNT, OSPW, OSPT, OSNW, OSNT, DRPW, DRPT, DRNW, DRNT, DSPW, DSPT, DSNW, DSNT).",
    "version": "1.0.0",
    "contact": {
      "name": "SkinGuide",
      "url": "https://skinguide.beauty"
    },
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://skinguide.beauty/api",
      "description": "Production server"
    }
  ],
  "paths": {
    "/products": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search skincare products",
        "description": "Search for skincare products based on skin type characteristics, product category, budget, and more. Returns products with compatible skin types, ingredients, and vegan status.",
        "tags": ["Products"],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "description": "Product category to filter by",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["Acne Treatments", "Anti-Aging Solutions", "Beauty Tools & Devices", "Cleansing Solutions", "Exfoliants & Peels", "Eye Care", "Facial Masks", "Hydration & Toning", "Makeup Products", "Moisturizers", "Oil Control Solutions", "Pigmentation Treatments", "Self-Tanning Products", "Serums & Targeted Treatments", "Soothing & Anti-Inflammatory", "Sun Protection"]
            }
          },
          {
            "name": "brand",
            "in": "query",
            "description": "Filter by brand name (partial match, case-insensitive). E.g., 'CeraVe', 'La Roche-Posay', 'Neutrogena'.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "skinType",
            "in": "query",
            "description": "Direct 4-letter Baumann skin type code (e.g., 'ORPW'). Alternative to using od/sr/pn/wt individually.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["ORPW", "ORPT", "ORNW", "ORNT", "OSPW", "OSPT", "OSNW", "OSNT", "DRPW", "DRPT", "DRNW", "DRNT", "DSPW", "DSPT", "DSNW", "DSNT"]
            }
          },
          {
            "name": "od",
            "in": "query",
            "description": "Skin oiliness filter. O = Oily skin, D = Dry skin.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["O", "D"]
            }
          },
          {
            "name": "sr",
            "in": "query",
            "description": "Skin sensitivity filter. S = Sensitive skin, R = Resistant skin.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["S", "R"]
            }
          },
          {
            "name": "pn",
            "in": "query",
            "description": "Skin pigmentation filter. P = Pigmented (prone to dark spots), N = Non-pigmented.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["P", "N"]
            }
          },
          {
            "name": "wt",
            "in": "query",
            "description": "Skin aging filter. W = Wrinkled (shows aging signs), T = Tight (firm skin).",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["W", "T"]
            }
          },
          {
            "name": "budget",
            "in": "query",
            "description": "Maximum price in dollars. Common values: 5, 10, 20, 50, 100. Use 101 for products over $100.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of products to return. Defaults to 50.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "keyword",
            "in": "query",
            "description": "Search keyword to match against product name and search keywords (case-insensitive). E.g., 'acne', 'anti-aging'.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ingredient",
            "in": "query",
            "description": "Filter products by ingredient name (partial match, case-insensitive). Matches against the product's ingredients list. E.g., 'retinol', 'hyaluronic acid', 'niacinamide', 'salicylic acid', 'vitamin c'.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with matching products",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductSearchResponse"
                },
                "example": {
                  "total": 3,
                  "url": "https://skinguide.beauty/product-search",
                  "query": {
                    "type": "Moisturizers",
                    "brand": "all",
                    "skinType": "ORPW",
                    "budget": 20,
                    "vegan": false,
                    "keyword": "all"
                  },
                  "products": [
                    {
                      "id": 1234,
                      "name": "CeraVe Moisturizing Cream",
                      "brand": "CeraVe",
                      "category": "Moisturizers",
                      "price": 16.99,
                      "currency": "USD",
                      "image": "https://example.com/image.jpg",
                      "link": "https://amazon.com/dp/...",
                      "isVegan": false,
                      "ingredients": ["Ceramides", "Hyaluronic Acid"],
                      "skinTypes": ["ORPW", "ORPT", "ORNW"]
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/skin-types": {
      "get": {
        "operationId": "getSkinTypes",
        "summary": "Get Baumann skin type information",
        "description": "Get information about Baumann skin types including title, description, and characteristics. Without a skinType parameter, returns all 16 skin types. With a skinType parameter, returns detailed info for that specific type.",
        "tags": ["Skin Types"],
        "parameters": [
          {
            "name": "skinType",
            "in": "query",
            "description": "Optional 4-letter Baumann skin type code to get detailed info for a specific type",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["ORPW", "ORPT", "ORNW", "ORNT", "OSPW", "OSPT", "OSNW", "OSNT", "DRPW", "DRPT", "DRNW", "DRNT", "DSPW", "DSPT", "DSNW", "DSNT"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with skin type information",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/SkinTypeListResponse" },
                    { "$ref": "#/components/schemas/SkinTypeDetailResponse" }
                  ]
                },
                "examples": {
                  "list": {
                    "summary": "List all skin types",
                    "value": {
                      "total": 16,
                      "skinTypes": [
                        {
                          "code": "ORPW",
                          "title": "☀️ ORPW Skin Type: The Sun Lover",
                          "description": "Detailed description of the skin type...",
                          "shortDescription": "Brief summary..."
                        }
                      ]
                    }
                  },
                  "detail": {
                    "summary": "Single skin type detail",
                    "value": {
                      "code": "ORPW",
                      "title": "☀️ ORPW Skin Type: The Sun Lover",
                      "description": "Detailed description...",
                      "shortDescription": "Brief summary...",
                      "routineDescription": "Routine-specific description..."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid skin type code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/routines": {
      "get": {
        "operationId": "getRoutine",
        "summary": "Get skincare routine for a skin type",
        "description": "Get the step-by-step skincare routine for a specific Baumann skin type. Returns routine steps with product type, action, and time of day. Can be filtered by gender and time of day.",
        "tags": ["Routines"],
        "parameters": [
          {
            "name": "skinType",
            "in": "query",
            "description": "The 4-letter Baumann skin type code (required)",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["ORPW", "ORPT", "ORNW", "ORNT", "OSPW", "OSPT", "OSNW", "OSNT", "DRPW", "DRPT", "DRNW", "DRNT", "DSPW", "DSPT", "DSNW", "DSNT"]
            }
          },
          {
            "name": "gender",
            "in": "query",
            "description": "Filter routine steps by gender",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["male", "female"]
            }
          },
          {
            "name": "timeOfDay",
            "in": "query",
            "description": "Filter routine steps by time of day. AM = morning, PM = evening.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["AM", "PM"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with routine steps",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoutineResponse"
                },
                "example": {
                  "skinType": "ORPW",
                  "title": "🔍 ORPW Skin Type: Complex but Completely Manageable",
                  "url": "https://skinguide.beauty/routine/ORPW",
                  "routineDescription": "This routine is designed to...",
                  "totalSteps": 8,
                  "filters": {
                    "gender": "all",
                    "timeOfDay": "all"
                  },
                  "steps": [
                    {
                      "step": 1,
                      "type": "Cleansing Solutions",
                      "timeOfDay": "AM",
                      "product": "Gentle foaming cleanser",
                      "action": "Apply to damp skin and rinse",
                      "gender": "All"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid skin type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/brands": {
      "get": {
        "operationId": "getBrands",
        "summary": "Get available skincare brands",
        "description": "Get a list of all unique skincare brands available in the SkinGuide product catalog.",
        "tags": ["Brands"],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response with list of brands",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandsResponse"
                },
                "example": {
                  "total": 150,
                  "url": "https://skinguide.beauty/product-search",
                  "brands": ["CeraVe", "La Roche-Posay", "Neutrogena"]
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProductSearchResponse": {
        "type": "object",
        "required": ["total", "query", "products"],
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of products returned"
          },
          "query": {
            "type": "object",
            "description": "Echo of the query parameters used",
            "properties": {
              "type": {
                "type": "string"
              },
              "brand": {
                "type": "string"
              },
              "skinType": {
                "oneOf": [
                  { "type": "string" },
                  {
                    "type": "object",
                    "properties": {
                      "oiliness": { "type": "string" },
                      "sensitivity": { "type": "string" },
                      "pigmentation": { "type": "string" },
                      "aging": { "type": "string" }
                    }
                  }
                ]
              },
              "budget": {
                "oneOf": [
                  { "type": "integer" },
                  { "type": "string" }
                ]
              },
              "keyword": {
                "type": "string"
              },
              "ingredient": {
                "type": "string"
              }
            }
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          }
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique product identifier"
          },
          "name": {
            "type": "string",
            "description": "Product name"
          },
          "brand": {
            "type": "string",
            "description": "Product brand"
          },
          "category": {
            "type": "string",
            "description": "Product category (e.g., Cleansing Solutions, Moisturizers, Serums & Targeted Treatments)"
          },
          "price": {
            "type": "number",
            "description": "Product price"
          },
          "currency": {
            "type": "string",
            "description": "Price currency (e.g., USD, AED)"
          },
          "image": {
            "type": "string",
            "format": "uri",
            "description": "Product image URL"
          },
          "link": {
            "type": "string",
            "format": "uri",
            "description": "Link to purchase the product"
          },
          "isVegan": {
            "type": "boolean",
            "description": "Whether the product is vegan"
          },
          "ingredients": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of product ingredients"
          },
          "skinTypes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["ORPW", "ORPT", "ORNW", "ORNT", "OSPW", "OSPT", "OSNW", "OSNT", "DRPW", "DRPT", "DRNW", "DRNT", "DSPW", "DSPT", "DSNW", "DSNT"]
            },
            "description": "Baumann skin types this product is suitable for"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          }
        }
      },
      "SkinTypeListResponse": {
        "type": "object",
        "required": ["total", "skinTypes"],
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of skin types"
          },
          "skinTypes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SkinTypeSummary"
            }
          }
        }
      },
      "SkinTypeSummary": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "4-letter Baumann skin type code"
          },
          "title": {
            "type": "string",
            "nullable": true,
            "description": "Display title (e.g., '☀️ ORPW Skin Type: The Sun Lover')"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Long description of the skin type"
          },
          "shortDescription": {
            "type": "string",
            "nullable": true,
            "description": "Brief summary of the skin type"
          }
        }
      },
      "SkinTypeDetailResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "4-letter Baumann skin type code"
          },
          "title": {
            "type": "string",
            "nullable": true,
            "description": "Display title (e.g., '☀️ ORPW Skin Type: The Sun Lover')"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Long description of the skin type"
          },
          "shortDescription": {
            "type": "string",
            "nullable": true,
            "description": "Brief summary of the skin type"
          },
          "routineDescription": {
            "type": "string",
            "nullable": true,
            "description": "Description specific to the skincare routine for this type"
          }
        }
      },
      "SkinType": {
        "type": "string",
        "enum": ["ORPW", "ORPT", "ORNW", "ORNT", "OSPW", "OSPT", "OSNW", "OSNT", "DRPW", "DRPT", "DRNW", "DRNT", "DSPW", "DSPT", "DSNW", "DSNT"],
        "description": "Baumann Skin Type - 4 letter code: O/D (Oily/Dry) + R/S (Resistant/Sensitive) + P/N (Pigmented/Non-pigmented) + W/T (Wrinkled/Tight)"
      },
      "BrandsResponse": {
        "type": "object",
        "required": ["total", "brands"],
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of brands"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Link to the product search page"
          },
          "brands": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Alphabetically sorted list of brand names"
          }
        }
      },
      "RoutineResponse": {
        "type": "object",
        "required": ["skinType", "totalSteps", "steps"],
        "properties": {
          "skinType": {
            "type": "string",
            "description": "The Baumann skin type code"
          },
          "title": {
            "type": "string",
            "nullable": true,
            "description": "Display title of the skin type"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Link to the routine page on SkinGuide (e.g., https://skinguide.beauty/routine/ORPW)"
          },
          "routineDescription": {
            "type": "string",
            "nullable": true,
            "description": "Description of the routine approach for this skin type"
          },
          "totalSteps": {
            "type": "integer",
            "description": "Number of routine steps returned"
          },
          "filters": {
            "type": "object",
            "properties": {
              "gender": {
                "type": "string",
                "description": "Gender filter applied"
              },
              "timeOfDay": {
                "type": "string",
                "description": "Time of day filter applied"
              }
            }
          },
          "steps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RoutineStep"
            }
          }
        }
      },
      "RoutineStep": {
        "type": "object",
        "properties": {
          "step": {
            "type": "integer",
            "nullable": true,
            "description": "Step number in the routine"
          },
          "type": {
            "type": "string",
            "nullable": true,
            "description": "Product type for this step (e.g., Cleansing Solutions, Moisturizers)"
          },
          "timeOfDay": {
            "type": "string",
            "nullable": true,
            "description": "When to apply: AM, PM, or Both"
          },
          "product": {
            "type": "string",
            "nullable": true,
            "description": "Recommended product or ingredient"
          },
          "action": {
            "type": "string",
            "nullable": true,
            "description": "How to apply or use the product"
          },
          "gender": {
            "type": "string",
            "nullable": true,
            "description": "Gender applicability: Male, Female, or All"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Products",
      "description": "Skincare product search operations"
    },
    {
      "name": "Skin Types",
      "description": "Baumann skin type information and classification"
    },
    {
      "name": "Routines",
      "description": "Skincare routine steps by skin type"
    },
    {
      "name": "Brands",
      "description": "Available skincare brands"
    }
  ],
  "externalDocs": {
    "description": "Learn more about Baumann Skin Types",
    "url": "https://skinguide.beauty/skin-types"
  }
}