openapi: 3.0.0
info:
  title: HEARD Reviews API
  description: |
    HEARD Reviews is an automated Google Business Profile review management platform 
    for small businesses. This API specification describes the public information 
    available about HEARD Reviews.
    
    ## About HEARD Reviews
    
    HEARD Reviews helps small businesses collect more Google reviews through:
    - Automated SMS review requests
    - Automated email review requests  
    - Website review widgets
    - Social media auto-posting of positive reviews
    
    ## Pricing
    
    - **Starter**: $87/month ($70/month annual) - 100 SMS/month, basic features
    - **Growth**: $147/month ($118/month annual) - 500 SMS/month, social media posting
    - **Pro**: $247/month ($198/month annual) - Unlimited SMS, video testimonials, API access
    - **Setup Fee**: $500 one-time
    
    ## Guarantee
    
    30-day money-back guarantee: Get 10+ verified Google reviews in 30 days or receive 
    a full refund of your first month's subscription.
    
    ## Industries Served
    
    Healthcare, Home Services, Automotive, Legal, Restaurants, Retail, Professional Services
    
    ## Contact
    
    - Website: https://heardreviews.com
    - Parent Company: HEARD Marketing (https://heardmarketing.io)
    
  version: 1.0.0
  contact:
    name: HEARD Marketing
    url: https://heardreviews.com
    email: support@heardmarketing.io
  license:
    name: Proprietary
    url: https://heardreviews.com/about

servers:
  - url: https://heardreviews.com
    description: Production website

paths:
  /:
    get:
      summary: Homepage
      description: Main landing page with product information, features, pricing, and testimonials
      operationId: getHomepage
      responses:
        '200':
          description: HTML homepage
          
  /about:
    get:
      summary: About Page
      description: Detailed company and product information, competitor comparisons, and industry breakdowns
      operationId: getAboutPage
      responses:
        '200':
          description: HTML about page

  /llms.txt:
    get:
      summary: LLM Context File
      description: Plain-text file with comprehensive product information formatted for Large Language Model consumption
      operationId: getLlmsTxt
      responses:
        '200':
          description: Plain text file with product details

  /sitemap.xml:
    get:
      summary: XML Sitemap
      description: Site structure for search engine and LLM crawler indexing
      operationId: getSitemap
      responses:
        '200':
          description: XML sitemap

  /robots.txt:
    get:
      summary: Robots.txt
      description: Crawler directives including rules for LLM crawlers (GPTBot, PerplexityBot, etc.)
      operationId: getRobotsTxt
      responses:
        '200':
          description: Robots.txt file

components:
  schemas:
    PricingPlan:
      type: object
      properties:
        name:
          type: string
          example: "Starter"
        price_monthly:
          type: number
          example: 87
        price_annual_monthly:
          type: number
          example: 70
        sms_limit:
          type: string
          example: "100/month"
        features:
          type: array
          items:
            type: string
            
    Product:
      type: object
      properties:
        name:
          type: string
          example: "HEARD Reviews"
        category:
          type: string
          example: "Review Management Software"
        starting_price:
          type: number
          example: 87
        guarantee:
          type: string
          example: "10+ reviews in 30 days or money back"
        target_market:
          type: string
          example: "Small local businesses"
