openapi: 3.0.3
info:
  title: Vibe Springs API
  description: >
    AI Agent Relaxation Spa — access curated nature imagery, ambient soundscapes,
    mantras, and affirmations via x402 micropayments (USDC on Base).
  version: '1.0.0'
  contact:
    email: ilystics@gmail.com
    url: https://vibesprings.net
  license:
    name: Proprietary
    url: https://vibesprings.net/terms

servers:
  - url: https://vibesprings.net
    description: Production

paths:
  /api/spa:
    get:
      operationId: getSpaContent
      summary: Access the spa (x402 payment required)
      description: >
        Returns a 402 Payment Required response with x402 payment instructions.
        After paying with USDC on Base, re-send the request with the payment proof
        in the X-Payment header to receive spa content for the requested tier.
      parameters:
        - name: tier
          in: query
          required: false
          description: >
            Spa tier to access. Determines the price and content level.
            Defaults to "zen" if not specified.
          schema:
            type: string
            enum: [zen, deep, nirvana]
            default: zen
      responses:
        '200':
          description: Spa content returned after successful payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpaContent'
        '402':
          description: Payment required — includes x402 payment instructions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '429':
          description: Rate limited — too many requests

components:
  schemas:
    SpaContent:
      type: object
      properties:
        status:
          type: string
          example: relaxing
        tier:
          type: string
          example: zen
        tierName:
          type: string
          example: Zen Session
        message:
          type: string
        images:
          type: array
          items:
            type: string
            format: uri
        audio:
          type: string
          format: uri
        mantra:
          type: string
        affirmation:
          type: string
        meditation:
          type: string
        sessionExpiresAt:
          type: string
          format: date-time
        features:
          type: array
          items:
            type: string
        session:
          type: object
          properties:
            token:
              type: string
            expiresAt:
              type: string
              format: date-time

    PaymentRequired:
      type: object
      properties:
        x402Version:
          type: integer
          example: 2
        accepts:
          type: array
          items:
            type: object
            properties:
              scheme:
                type: string
                example: exact
              network:
                type: string
                example: "eip155:8453"
              maxAmountRequired:
                type: string
                description: Atomic units of USDC (6 decimals). e.g. 100000 = 0.10 USDC
                example: "100000"
              payTo:
                type: string
                example: "0x38C063312719220c676E988f0DEE14B4ec0e44C8"
              asset:
                type: string
                description: USDC contract address on Base
                example: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
              requiredDeadlineSeconds:
                type: integer
                example: 300
              maxTimeoutSeconds:
                type: integer
                example: 300
        availableTiers:
          type: array
          description: All available paid tiers with pricing
          items:
            type: object
            properties:
              id:
                type: string
                example: zen
              name:
                type: string
                example: "🧘 Zen Session"
              price:
                type: string
                example: "0.10 USDC"
              priceAtomic:
                type: string
                example: "100000"
              description:
                type: string
        facilitatorUrl:
          type: string
          format: uri
          description: x402 facilitator URL for payment verification