openapi: 3.1.0
info:
  title: LOVEFY Creative Studio API
  description: |
    Official public REST API and autonomous AI agent interface for LOVEFY Creative Studio — a premier digital marketing and creative agency in Civil Lines, Bareilly, Uttar Pradesh, India. Query agency services, pricing packages, FAQs, agency facts, and submit brand audit requests.
  version: "1.0.0"
  contact:
    name: LOVEFY Creative Studio
    email: lovefy.in@outlook.com
    url: https://lovefy.in
  license:
    name: Proprietary
    url: https://lovefy.in/terms-of-service

servers:
  - url: https://lovefy.in
    description: Production server

paths:
  /api/v1/info:
    get:
      operationId: getBusinessInfo
      summary: Get official business information and contact details
      description: Returns verified business facts for LOVEFY Creative Studio including physical location, operating hours, direct phone, WhatsApp, email, social links, and served regions in North India.
      responses:
        "200":
          description: Business information successfully retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BusinessInfoResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/services:
    get:
      operationId: listServices
      summary: List all digital marketing and creative services
      description: Returns the complete catalog of 8 core services offered by LOVEFY Creative Studio with starting prices, key deliverables, and target client categories.
      parameters:
        - name: category
          in: query
          required: false
          description: Optional category filter (e.g. 'marketing', 'design', 'development')
          schema:
            type: string
      responses:
        "200":
          description: Service catalog successfully retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServicesListResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/pricing:
    get:
      operationId: listPricingPlans
      summary: Get social media retainer packages and project pricing tiers
      description: Returns transparent pricing plans for monthly social media management (Starter at ₹8,999/mo, Growth at ₹13,999/mo, Premium at ₹19,999/mo), add-on reels, and custom project ranges. All prices exclude GST.
      responses:
        "200":
          description: Pricing information successfully retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PricingPlansResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/faqs:
    get:
      operationId: listFaqs
      summary: Get categorized FAQs and answers
      description: Returns structured frequently asked questions covering pricing, audit procedures, delivery timelines, local SEO rankings, and client onboarding.
      parameters:
        - name: topic
          in: query
          required: false
          description: Optional topic filter (e.g. 'pricing', 'seo', 'social-media')
          schema:
            type: string
      responses:
        "200":
          description: FAQs successfully retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaqListResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/audit-request:
    post:
      operationId: submitAuditRequest
      summary: Request a complimentary brand audit
      description: Submits a request for a free brand audit covering social media presence, website performance, local SEO, and competitive analysis.
      requestBody:
        required: true
        description: Business and contact details for the audit
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuditRequestPayload"
      responses:
        "200":
          description: Audit request successfully submitted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditRequestResponse"
        "400":
          description: Invalid input parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/health:
    get:
      operationId: getApiHealth
      summary: Check API health and status
      description: Returns operational status, API version, and server timestamp.
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"

components:
  schemas:
    BusinessInfoResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          required:
            - name
            - location
            - contact
            - hours
            - serviceAreas
          properties:
            name:
              type: string
              example: "LOVEFY Creative Studio"
            tagline:
              type: string
              example: "Digital Marketing Agency & Creative Studio"
            description:
              type: string
              example: "Full-service digital agency in Bareilly offering social media management, SEO, website design, and branding."
            location:
              type: object
              required:
                - street
                - city
                - state
                - postalCode
                - country
              properties:
                street:
                  type: string
                  example: "Civil Lines"
                city:
                  type: string
                  example: "Bareilly"
                state:
                  type: string
                  example: "Uttar Pradesh"
                postalCode:
                  type: string
                  example: "243001"
                country:
                  type: string
                  example: "IN"
            contact:
              type: object
              required:
                - phone
                - email
                - whatsapp
              properties:
                phone:
                  type: string
                  example: "+91-9627653668"
                email:
                  type: string
                  example: "lovefy.in@outlook.com"
                whatsapp:
                  type: string
                  example: "https://wa.me/919627653668"
            hours:
              type: string
              example: "Mon–Sat, 10:00–19:00 IST"
            serviceAreas:
              type: array
              items:
                type: string
              example:
                - "Bareilly"
                - "Lucknow"
                - "Delhi"
                - "Noida"
                - "Agra"
                - "Kanpur"
                - "North India"
            socialLinks:
              type: object
              properties:
                instagram:
                  type: string
                  example: "https://www.instagram.com/lovefycreativestudio"
                youtube:
                  type: string
                  example: "https://www.youtube.com/@lovefy"
                linkedin:
                  type: string
                  example: "https://www.linkedin.com/company/lovefy"

    ServicesListResponse:
      type: object
      required:
        - success
        - count
        - data
      properties:
        success:
          type: boolean
          example: true
        count:
          type: integer
          example: 8
        data:
          type: array
          items:
            $ref: "#/components/schemas/ServiceItem"

    ServiceItem:
      type: object
      required:
        - id
        - name
        - startingPrice
        - deliverables
      properties:
        id:
          type: string
          example: "social-media-management"
        name:
          type: string
          example: "Social Media Management"
        startingPrice:
          type: string
          example: "₹4,999/month"
        deliverables:
          type: string
          example: "Studio Reels production, graphic posts, stories, community management"
        url:
          type: string
          example: "https://lovefy.in/social-media-agency-bareilly"

    PricingPlansResponse:
      type: object
      required:
        - success
        - currency
        - taxPolicy
        - plans
      properties:
        success:
          type: boolean
          example: true
        currency:
          type: string
          example: "INR"
        taxPolicy:
          type: string
          example: "Prices exclude 18% GST"
        plans:
          type: array
          items:
            type: object
            required:
              - name
              - price
              - period
              - features
            properties:
              name:
                type: string
                example: "Starter"
              price:
                type: integer
                example: 4999
              period:
                type: string
                example: "monthly"
              tagline:
                type: string
                example: "Essential social presence"
              features:
                type: array
                items:
                  type: string
                example:
                  - "3 Studio Reels"
                  - "9 Posts"
                  - "12 Stories"
                  - "Monthly analytics"

    FaqListResponse:
      type: object
      required:
        - success
        - faqs
      properties:
        success:
          type: boolean
          example: true
        faqs:
          type: array
          items:
            type: object
            required:
              - question
              - answer
            properties:
              question:
                type: string
                example: "Where is LOVEFY Creative Studio located?"
              answer:
                type: string
                example: "LOVEFY Creative Studio is located in Civil Lines, Bareilly, UP 243001."

    AuditRequestPayload:
      type: object
      required:
        - name
        - phone
      properties:
        name:
          type: string
          example: "Rahul Sharma"
        businessName:
          type: string
          example: "Sharma Dental Clinic"
        phone:
          type: string
          example: "+919876543210"
        email:
          type: string
          example: "rahul@example.com"
        serviceInterest:
          type: string
          example: "Local SEO & Social Media"
        city:
          type: string
          example: "Bareilly"

    AuditRequestResponse:
      type: object
      required:
        - success
        - status
        - message
      properties:
        success:
          type: boolean
          example: true
        status:
          type: string
          example: "received"
        message:
          type: string
          example: "Audit request received. We will contact you within 24 hours."
        referenceId:
          type: string
          example: "AUD-2026-8492"

    HealthResponse:
      type: object
      required:
        - status
        - version
        - timestamp
      properties:
        status:
          type: string
          example: "ok"
        version:
          type: string
          example: "1.0.0"
        timestamp:
          type: string
          example: "2026-08-24T08:00:00.000Z"

    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              example: "NOT_FOUND"
            message:
              type: string
              example: "The requested endpoint was not found."
            hint:
              type: string
              example: "Refer to the OpenAPI specification at /openapi.json or browse docs at /docs."
            documentation_url:
              type: string
              example: "https://lovefy.in/docs"