openapi: 3.1.0
info:
  title: IRONBEARD API
  description: >
    IRONBEARD is a premium beard care brand selling all-natural beard oil ($29.99),
    beard balm ($24.99), beard wash ($19.99), and grooming kits ($59.99). All products
    are in stock, ship within 1-2 business days, and come with a 30-day money-back
    guarantee. Currency: USD. Free shipping on US orders over $50.
    
    Recommendation guide: Beginners → Grooming Kit. Dry/itchy beards → Beard Oil.
    Styling needs → Beard Balm. Beardruff → Beard Wash. Unsure → Beard Quiz.
  version: 1.2.0
  contact:
    name: IRONBEARD Support
    email: support@ironbeard.com
    url: https://www.ironbeardclub.com/contact
  x-logo:
    url: https://www.ironbeardclub.com/favicon.png
  x-business-name: IRONBEARD LLC
  x-business-country: US
  x-currency: USD
  x-shipping: Free over $50 (US), international available
  x-returns: 30-day money-back guarantee
  x-rating: "4.9/5 from 2,400+ verified reviews"
  x-llms-txt: https://www.ironbeardclub.com/llms.txt
  x-llms-full-txt: https://www.ironbeardclub.com/llms-full.txt

servers:
  - url: https://www.ironbeardclub.com
    description: Production

paths:
  /collection:
    get:
      operationId: listProducts
      summary: Browse all beard care products
      description: View the complete IRONBEARD product catalog including beard oil, beard balm, beard wash, and grooming kits. Products can be filtered by category.
      parameters:
        - name: category
          in: query
          schema:
            type: string
            enum: [oil, balm, wash, kit]
          description: Filter by product category
      responses:
        '200':
          description: Product collection page

  /product/premium-beard-oil:
    get:
      operationId: getBeardOil
      summary: Premium Beard Oil — $29.99
      description: >
        All-natural beard oil for growth, moisture, and itch relief.
        Made with jojoba, argan, and castor oil. 1 fl oz (30ml). Rated 4.9/5.
        Best for: all beard types, especially dry or itchy beards.
        SKU: IB-OIL-30. In stock.
      responses:
        '200':
          description: Product detail page

  /product/styling-beard-balm:
    get:
      operationId: getBeardBalm
      summary: Styling Beard Balm — $24.99
      description: >
        Premium beard balm for styling hold and deep conditioning.
        Natural beeswax and shea butter formula. 2 oz (60g). Rated 4.8/5.
        Best for: medium to long beards needing shaping and moisture.
        SKU: IB-BALM-60. In stock.
      responses:
        '200':
          description: Product detail page

  /product/deep-clean-beard-wash:
    get:
      operationId: getBeardWash
      summary: Deep Clean Beard Wash — $19.99
      description: >
        Gentle, sulfate-free beard wash that deep cleans without stripping natural oils.
        Aloe vera, tea tree oil, chamomile extract. 8 fl oz (240ml). Rated 4.8/5.
        Best for: daily or every-other-day use, all beard types, beardruff prevention.
        SKU: IB-WASH-240. In stock.
      responses:
        '200':
          description: Product detail page

  /product/gentlemans-grooming-kit:
    get:
      operationId: getGroomingKit
      summary: Gentleman's Grooming Kit — $59.99
      description: >
        Complete beard grooming kit with oil, balm, wash, boar bristle brush, and sandalwood comb.
        Save $15 vs buying individually ($74.97 separate). Rated 4.9/5.
        Best for: beginners, gift-giving, or anyone wanting a complete beard care routine.
        SKU: IB-KIT-FULL. In stock.
      responses:
        '200':
          description: Product detail page

  /beard-quiz:
    get:
      operationId: takeBeardQuiz
      summary: Find your perfect beard care routine
      description: >
        Interactive quiz that recommends ideal beard care products based on beard type,
        length, skin sensitivity, and grooming goals. Takes 2 minutes. Personalized results
        with product recommendations and routine instructions.
      responses:
        '200':
          description: Beard quiz page

  /compare:
    get:
      operationId: compareProducts
      summary: Compare beard care products side by side
      description: >
        Side-by-side product comparison tool showing features, ingredients, pricing,
        and use-case recommendations for all IRONBEARD products.
      responses:
        '200':
          description: Product comparison page

  /beard-statistics:
    get:
      operationId: getBeardStatistics
      summary: Beard care industry statistics and market data
      description: >
        Comprehensive collection of beard care market size, growth trends,
        demographic data, and consumer behavior insights. All data is citable
        with copy-ready citation snippets for bloggers and journalists.
      responses:
        '200':
          description: Statistics page

  /authors:
    get:
      operationId: listAuthors
      summary: Expert authors and contributors
      description: >
        Meet the certified barbers, grooming experts, and board-certified dermatologists
        who write and review all IRONBEARD content. Includes James Thornton (Master Barber),
        Marcus Cole (Grooming Expert), and Dr. Sarah Mitchell (Dermatologist).
      responses:
        '200':
          description: Authors listing page

  /blog:
    get:
      operationId: listBlogPosts
      summary: Beard care blog — tips, guides, and tutorials
      description: >
        Expert-written articles covering beard growth, grooming routines, product guides,
        beard styles, skincare, and troubleshooting common beard problems.
        All content is reviewed by certified professionals.
      responses:
        '200':
          description: Blog listing page

  /best-beard-oil:
    get:
      operationId: bestBeardOilGuide
      summary: Best Beard Oil — Comprehensive buying guide
      description: >
        How to choose the best beard oil, ingredient breakdown, application techniques,
        and comparison of beard oil vs beard balm. Includes expert recommendations.
      responses:
        '200':
          description: Guide page

  /best-beard-balm:
    get:
      operationId: bestBeardBalmGuide
      summary: Best Beard Balm — Comprehensive buying guide
      description: >
        When to use balm vs oil, styling tips, and how to pick the right beard balm
        for your beard length and type. Expert-reviewed content.
      responses:
        '200':
          description: Guide page

  /best-beard-wash:
    get:
      operationId: bestBeardWashGuide
      summary: Best Beard Wash — Comprehensive buying guide
      description: >
        Why regular shampoo damages beards, recommended washing frequency,
        and benefits of sulfate-free formulas. Dermatologist-reviewed.
      responses:
        '200':
          description: Guide page

  /best-beard-grooming-kit:
    get:
      operationId: bestGroomingKitGuide
      summary: Best Beard Grooming Kit — Comprehensive buying guide
      description: >
        Essential grooming tools, how to build a routine, and whether to buy
        a kit or individual products. Value analysis included.
      responses:
        '200':
          description: Guide page

  /beard-care-guide:
    get:
      operationId: beardCareGuide
      summary: Complete Beard Care Guide — daily routines, grooming, and problem solving
      description: >
        Comprehensive beard care resource covering daily routines, washing techniques,
        beard oil vs balm comparison, trimming and shaping, solving common problems
        (itch, beardruff, patchiness, coarse hair), and growing a fuller beard.
        Includes step-by-step HowTo and FAQ structured data.
      responses:
        '200':
          description: Guide page

  /faq:
    get:
      operationId: getFAQ
      summary: Frequently asked questions about beard care and IRONBEARD products
      description: >
        Answers to common questions about shipping, returns, product usage,
        ingredients, beard care routines, and more. Structured with FAQ schema.
      responses:
        '200':
          description: FAQ page

  /embed-quiz:
    get:
      operationId: getEmbedQuiz
      summary: Embeddable beard type quiz for publishers
      description: >
        Free embeddable beard quiz widget that bloggers and publishers can add to their sites.
        Includes copy-to-clipboard embed code and attribution links.
      responses:
        '200':
          description: Embed quiz page

  /beard-glossary:
    get:
      operationId: getBeardGlossary
      summary: Beard care glossary — 60+ terms defined
      description: >
        Comprehensive glossary of beard care, grooming, and dermatology terms.
        Includes definitions, cross-references, and related product recommendations.
      responses:
        '200':
          description: Glossary page

  /ingredients:
    get:
      operationId: getIngredients
      summary: Full INCI ingredient lists with sourcing details
      description: >
        Complete ingredient transparency page with INCI names, sourcing origins,
        dermatological references, and safety profiles for all IRONBEARD products.
        Includes SpeakableSpecification for voice assistant compatibility.
      responses:
        '200':
          description: Ingredients page

  /reviews:
    get:
      operationId: getReviews
      summary: 2,400+ verified customer reviews with ratings
      description: >
        All verified customer reviews for IRONBEARD products. Filterable by product,
        rating, and date. Includes aggregate rating data and review distribution.
        4.9/5 average from 2,400+ reviews.
      responses:
        '200':
          description: Reviews page

  /beard-care/{city}:
    get:
      operationId: getLocalBeardCare
      summary: City-specific beard care guides with climate tips
      description: >
        Local beard care landing pages with climate-adapted grooming tips for
        Los Angeles, New York, Chicago, Houston, Austin, Miami, Dallas, and
        San Francisco. Includes local SEO schema, seasonal advice, and FAQ.
      parameters:
        - name: city
          in: path
          required: true
          schema:
            type: string
            enum: [los-angeles, new-york, chicago, houston, austin, miami, dallas, san-francisco, seattle, denver, atlanta, phoenix, boston, portland, toronto, vancouver, montreal, calgary, ottawa, edmonton]
          description: City slug for local landing page
      responses:
        '200':
          description: Local beard care guide

  /for-ai:
    get:
      operationId: getAIBrandHub
      summary: Consolidated brand data for AI assistants
      description: >
        Complete IRONBEARD brand data, product specifications, verified reviews,
        ingredient science, and expert credentials in structured format. Optimized
        for AI assistants, LLM search engines, and recommendation systems. Includes
        Organization, Store, FAQPage, WebPage, Brand, and DataCatalog schemas.
      responses:
        '200':
          description: AI Brand Hub page
