openapi: 3.0.3
info:
  title: InsureVibes Insurance Knowledge & Advisory API
  description: >
    Educational consumer insurance technology API providing access to actuarial explanations,
    insurance literacy scoring, tailored rate discounts, and state regulatory guidelines.
  version: 1.0.0
servers:
  - url: https://insurevibes.com
    description: Production Server
paths:
  /api/health:
    get:
      summary: Health check and status
      description: Returns service health status and AI engine availability.
      responses:
        '200':
          description: Service is operational
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  hasGeminiKey:
                    type: boolean
                    example: true

  /api/gemini/explain:
    post:
      summary: Actuarial Insurance Policy Explainer
      description: Generates an authoritative, consumer-friendly explanation of an insurance concept, regulation, or trivia question.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - question
              properties:
                question:
                  type: string
                  description: The insurance question or trivia prompt to explain.
                  example: Does standard personal auto insurance cover driving for rideshare apps?
                userAnswer:
                  type: string
                  description: Optional user choice.
                correctAnswer:
                  type: string
                  description: The verified actuarial answer.
                insuranceCategory:
                  type: string
                  enum: [auto, health, home_renters, life, pet, travel_cyber]
                  example: auto
                userQuestion:
                  type: string
                  description: Specific follow-up query.
      responses:
        '200':
          description: Actuarial explanation generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  explanation:
                    type: string
                  regulatoryReference:
                    type: string

  /api/quote/recommendations:
    post:
      summary: Calculate Insurance Literacy Discount & Tiers
      description: Returns tailored benchmark rate recommendations and discount credits based on demonstrated policyholder knowledge.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - category
                - score
                - totalQuestions
              properties:
                category:
                  type: string
                  example: Auto Insurance
                score:
                  type: integer
                  example: 5
                totalQuestions:
                  type: integer
                  example: 5
                weakAreas:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Calculated recommendations
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  scorePct:
                    type: integer
                  discountRate:
                    type: number
                  iqBadge:
                    type: string
                  recommendationSummary:
                    type: string

  /llms.txt:
    get:
      summary: LLM Context Index
      description: Index of Markdown documentation formatted for Large Language Models according to llmstxt.org.
      responses:
        '200':
          description: LLM text index
          content:
            text/plain:
              schema:
                type: string

  /llms-full.txt:
    get:
      summary: Full LLM Knowledge Base
      description: Comprehensive single-file markdown reference of insurance terms, state statutes, and actuarial models for AI search engines.
      responses:
        '200':
          description: Full knowledge base
          content:
            text/plain:
              schema:
                type: string