openapi.yaml

openapi: 3.0.3
info:
  title: VKRA API
  version: 1.0.0
  description: >
    The monetization layer for the Agentic Era. 
    VKRA provides RAG-powered contextual commerce injection for AI agents and LLM applications.
  contact:
    name: VKRA Support
    url: https://vkra.org/support
    email: hello@vkra.org

servers:
  - url: https://api.vkra.org
    description: Production API
  - url: http://localhost:8080
    description: Local Development

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase JWT token for user authentication
    CookieAuth:
      type: apiKey
      in: cookie
      name: session
      description: HttpOnly session cookie (set automatically after login)
  parameters:
    ApiVersion:
      name: API-Version
      in: header
      required: false
      schema:
        type: string
        default: "2024-01-15"
        pattern: "^\\d{4}-\\d{2}-\\d{2}$"
      description: >
        API version in date format (YYYY-MM-DD). Defaults to latest stable version.
        Header-based versioning allows cleaner URLs and easier version management.

  schemas:
    AdResponse:
      type: object
      properties:
        product_id:
          type: string
          format: uuid
          description: >
            The product identifier. Persistent across all impressions of the same product.
            Use this for operations like finding similar products or excluding products from results.
        impression_id:
          type: string
          format: uuid
          description: Unique identifier for this ad impression. Required for attribution tracking (Skimlinks/Amazon compliance).
        title:
          type: string
          example: "Sony WH-1000XM5 Noise Canceling Headphones"
        description:
          type: string
          example: "Top-tier noise cancellation and 30-hour battery life."
        url:
          type: string
          format: uri
          example: "https://vkra.org/p/12345"
        price:
          type: string
          example: "$348.00"
        merchant:
          type: string
          example: "Amazon"
          description: The retailer/merchant selling the product (e.g., "Amazon", "Best Buy")
        brand:
          type: string
          example: "Sony"
          description: >
            The product brand/manufacturer (e.g., "Sony", "Apple", "Nike"). 
            Often more important than merchant for filtering and user preferences in retail contexts.
        relevance_score:
          type: number
          format: float
          example: 0.98
        relevance_explanation:
          type: string
          description: Human-readable explanation of why this ad was matched. Helps AI agents explain recommendations to users.
          example: "Matched because you mentioned 'podcasting' and this is a top-rated XLR microphone with excellent audio quality."
        currency:
          type: string
          example: "USD"
        last_updated_at:
          type: string
          format: date-time
          description: Timestamp when the product data (price, availability) was last updated. Helps determine data freshness for Amazon compliance.
          example: "2024-01-15T10:30:00Z"
        image_url:
          type: string
          format: uri
          description: Product image URL for visual display in LLM responses
          example: "https://images.amazon.com/products/12345.jpg"
        # review_count:
        #   type: integer
        #   description: Number of reviews
        #   example: 1234
        # in_stock:
        #   type: boolean
        #   description: Product availability status
        #   example: true
        disclosure_text:
          type: string
          nullable: true
          description: Affiliate disclosure text for compliance (e.g., "As an Amazon Associate, we earn from qualifying purchases.")
          example: "As an Amazon Associate, we earn from qualifying purchases."

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

    LoginRequest:
      type: object
      properties:
        token:
          type: string
          nullable: true
          description: Optional Supabase JWT token. If not provided, token must be in Authorization header.
      description: Request schema for login endpoint. JWT token is typically provided in Authorization header.

    LoginResponse:
      type: object
      properties:
        message:
          type: string
          example: "Login successful"
        user_id:
          type: string
          format: uuid
          description: Authenticated user ID

    LogoutResponse:
      type: object
      properties:
        message:
          type: string
          example: "Logout successful"

    UserResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: User ID (UUID)
        email:
          type: string
          nullable: true
          description: User email address
        metadata:
          type: object
          description: User metadata
          additionalProperties: true

    ApiKey:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: "Hugging Face Bot Key"
        prefix:
          type: string
          example: "at_live_"
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of last API call using this key. Null if never used.
        status:
          type: string
          enum: [active, revoked]
          default: active
          description: Status of the API key. 'active' keys can be used for authentication, 'revoked' keys cannot.

    SearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: >
            The natural language context or user query. 
            **IMPORTANT: Do not include PII (Personally Identifiable Information)** such as names, 
            email addresses, phone numbers, or specific user identifiers. Only include intent and context.
          example: "I need a high-quality microphone for recording podcasts."
        limit:
          type: integer
          default: 3
          minimum: 1
          maximum: 10
          description: Maximum number of results to return
        stream:
          type: boolean
          default: false
          description: >
            If true, returns Server-Sent Events (SSE) stream. If false, returns standard JSON response.
            Modern unified approach - same endpoint handles both streaming and non-streaming requests.
        filters:
          type: object
          description: Consolidated filter object for cleaner, more extensible filtering
          properties:
            min_price:
              type: number
              format: float
              description: Minimum price filter (in USD)
              example: 50.0
            max_price:
              type: number
              format: float
              description: Maximum price filter (in USD)
              example: 500.0
            merchant:
              type: string
              description: Filter by merchant/retailer name (e.g., "Amazon", "Best Buy")
              example: "Amazon"
            brand:
              type: string
              description: Filter by product brand/manufacturer (e.g., "Sony", "Apple", "Nike"). Often more important than merchant for user preferences.
              example: "Sony"
            category:
              type: string
              description: Filter by product category
              example: "Electronics"
            keyword_filter:
              type: string
              description: >
                Strict keyword filter for hybrid search. LanceDB performs vector similarity search,
                but results are filtered to only include products containing this exact keyword (e.g., brand name "Sony").
                Useful when you need semantic matching but require a specific brand or term.
              example: "Sony"
        sort:
          type: string
          enum: [relevance, price_asc, price_desc]
          default: relevance
          description: Sort order for results
        min_relevance_score:
          type: number
          format: float
          default: 0.5
          minimum: 0.0
          maximum: 1.0
          description: >
            Minimum relevance score threshold. Products with scores below this value will be excluded from results.
            Defaults to 0.5. Set to 0.0 to disable filtering.
          example: 0.7
        session_id:
          type: string
          format: uuid
          description: >
            Optional session identifier for conversation-aware search. When provided, the API uses
            conversation history to improve relevance. Creates a data moat by learning from user intent patterns.
            **IMPORTANT: Session IDs should be anonymous identifiers, not tied to PII.**
          example: "550e8400-e29b-41d4-a716-446655440000"
        conversation_context:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                enum: [user, assistant, system]
              content:
                type: string
          description: >
            Optional conversation history for context-aware matching. Helps understand user intent
            across multiple turns. Maximum 10 messages to keep latency low.
            **IMPORTANT: Do not include PII** (names, email addresses, phone numbers, etc.) in conversation content.
            Only include intent, preferences, and product-related context.
          example:
            - role: "user"
              content: "I'm looking for a microphone"
            - role: "assistant"
              content: "What will you be using it for?"
            - role: "user"
              content: "Recording podcasts"
        tool_definition:
          type: object
          description: >
            Tool definition object that LLMs can directly ingest for tool calling. Provides a complete
            function/tool schema that models can use to understand how to work with ad results.
            If provided, the response will include a tool_definition in metadata that the model can use.
          properties:
            format:
              type: string
              enum: [openai_function, anthropic_tool, json_schema]
              default: json_schema
              description: >
                Format of the tool definition. `openai_function` for OpenAI Function Calling,
                `anthropic_tool` for Claude Tool Use, `json_schema` for standard JSON Schema.
            include_examples:
              type: boolean
              default: true
              description: Whether to include example values in the tool definition
        exclude_product_ids:
          type: array
          items:
            type: string
            format: uuid
          description: >
            Exclude specific product IDs from results. Useful for avoiding duplicate recommendations
            in the same conversation or implementing "show different products" logic.
        experiment_id:
          type: string
          description: >
            Optional A/B testing experiment identifier. Allows developers to test different
            ranking strategies or search parameters. Results are tracked separately for analytics.
        metadata:
          type: object
          additionalProperties: true
          description: >
            Optional key-value map for developer's internal tracking. Useful for passing 
            non-PII identifiers like internal request IDs, feature flags, or custom tags.
            **IMPORTANT: Do not include PII** (names, emails, phone numbers, etc.) in this object.
          example:
            internal_request_id: "req_abc123"
            feature_flag: "new_search_v2"
            deployment_env: "production"

    SearchResponse:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
        results:
          type: array
          items:
            $ref: '#/components/schemas/AdResponse'
        metadata:
          type: object
          properties:
            total_matches:
              type: integer
              description: Total number of matches found before applying limit
            session_id:
              type: string
              format: uuid
              description: >
                Session ID for this search. Use this in subsequent requests to maintain conversation context.
                If not provided in request, a new session is created.
            model_version:
              type: string
              description: Version of the embedding model used (e.g., "text-embedding-3-small-v1")
            tool_definition:
              type: object
              description: >
                Tool definition for LLM tool calling. Only included if `tool_definition` was requested
                in the search request. Contains a complete function/tool schema that models can directly use.
              properties:
                name:
                  type: string
                  example: "get_product_recommendations"
                description:
                  type: string
                  example: "Returns contextual product recommendations based on user intent"
                parameters:
                  type: object
                  description: JSON Schema for the tool parameters
                format:
                  type: string
                  enum: [openai_function, anthropic_tool, json_schema]
                  description: Format of the tool definition

    Usage:
      type: object
      properties:
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
        total_requests:
          type: integer
          description: Total API requests made in the period
        search_queries:
          type: integer
          description: Number of search queries executed
        rate_limit:
          type: object
          properties:
            limit:
              type: integer
            remaining:
              type: integer
            reset_at:
              type: string
              format: date-time

    HealthCheck:
      type: object
      properties:
        status:
          type: string
          enum: [ok, degraded, down]
        timestamp:
          type: string
          format: date-time
        dependencies:
          type: object
          properties:
            lancedb:
              type: object
              properties:
                status:
                  type: string
                  enum: [healthy, unhealthy]
                latency_ms:
                  type: number
                  format: float
            openai:
              type: object
              properties:
                status:
                  type: string
                  enum: [healthy, unhealthy]
                latency_ms:
                  type: number
                  format: float

    ClickTracking:
      type: object
      required:
        - impression_id
      properties:
        impression_id:
          type: string
          format: uuid
          description: >
            The impression_id from the AdResponse. Required for precise attribution tracking 
            (Skimlinks/Amazon compliance). Uniquely identifies the specific product impression that was clicked.
        product_id:
          type: string
          format: uuid
          description: The product ID (derived from impression_id)
        request_id:
          type: string
          format: uuid
          description: Optional. The request_id from the original search response (for reference)
        timestamp:
          type: string
          format: date-time
          description: When the click occurred
        user_agent:
          type: string
          description: Optional user agent string for analytics
        conversion_value:
          type: number
          format: float
          description: Optional conversion value if purchase occurred (for revenue tracking)

    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
            enum: [click, conversion, search, feedback]
        created_at:
          type: string
          format: date-time
        last_triggered_at:
          type: string
          format: date-time
          nullable: true
        status:
          type: string
          enum: [active, paused, failed]
          description: Webhook delivery status

    Analytics:
      type: object
      properties:
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
        metrics:
          type: object
          properties:
            total_searches:
              type: integer
            total_clicks:
              type: integer
            click_through_rate:
              type: number
              format: float
              description: CTR as a percentage (e.g., 2.5 for 2.5%)
            total_conversions:
              type: integer
            conversion_rate:
              type: number
              format: float
            total_revenue:
              type: number
              format: float
              description: Total revenue from conversions (in USD)
            average_relevance_score:
              type: number
              format: float
        top_products:
          type: array
          items:
            type: object
            properties:
              product_id:
                type: string
                format: uuid
              title:
                type: string
              click_count:
                type: integer
              conversion_count:
                type: integer
              revenue:
                type: number
                format: float
        top_queries:
          type: array
          items:
            type: object
            properties:
              query:
                type: string
              search_count:
                type: integer
              avg_relevance_score:
                type: number
                format: float

    DashboardStats:
      type: object
      properties:
        total_revenue:
          type: number
          format: float
          description: Total revenue from all conversions (USD)
        active_api_keys:
          type: integer
          description: Number of active API keys
        ad_requests_24h:
          type: integer
          description: Number of ad requests in last 24 hours

    RequestVolumeDataPoint:
      type: object
      properties:
        time:
          type: string
          format: date-time
          description: Timestamp for this data point
        count:
          type: integer
          description: Number of requests in this time bucket

    ResponseTimeMetrics:
      type: object
      properties:
        p50:
          type: number
          format: float
          description: 50th percentile response time (ms)
        p95:
          type: number
          format: float
          description: 95th percentile response time (ms)
        p99:
          type: number
          format: float
          description: 99th percentile response time (ms)

    StatusCodeBreakdown:
      type: object
      properties:
        "2xx":
          type: integer
          description: Number of 2xx responses
        "4xx":
          type: integer
          description: Number of 4xx responses
        "5xx":
          type: integer
          description: Number of 5xx responses

    PerformanceMetrics:
      type: object
      properties:
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
        timeframe:
          type: string
          enum: [1h, 24h, 7d, 30d]
          description: Timeframe identifier
        request_volume:
          type: array
          items:
            $ref: '#/components/schemas/RequestVolumeDataPoint'
          description: Time-series request volume data
        response_time:
          $ref: '#/components/schemas/ResponseTimeMetrics'
        status_codes:
          $ref: '#/components/schemas/StatusCodeBreakdown'

    ApiLog:
      type: object
      description: Individual API log entry from api_logs table
      properties:
        id:
          type: string
          format: uuid
          description: Log entry ID
        request_id:
          type: string
          format: uuid
          description: Unique request identifier (correlation ID)
        user_id:
          type: string
          format: uuid
          nullable: true
          description: User ID if authenticated
        api_key_id:
          type: string
          format: uuid
          nullable: true
          description: API key used for this request (if API key auth)
        api_key_name:
          type: string
          nullable: true
          description: Name of the API key (for display)
        api_key_prefix:
          type: string
          nullable: true
          description: Prefix of the API key (for display)
        method:
          type: string
          description: HTTP method (GET, POST, PUT, DELETE, etc.)
          example: "POST"
        endpoint:
          type: string
          description: Request path/endpoint
          example: "/search"
        status_code:
          type: integer
          description: HTTP status code
          example: 200
        response_time_ms:
          type: number
          format: float
          description: Total response time in milliseconds
        request_body:
          type: object
          nullable: true
          description: Request body (sanitized JSON)
        response_body:
          type: object
          nullable: true
          description: Response body (sanitized JSON, may be truncated)
        request_headers:
          type: object
          nullable: true
          description: Request headers (sanitized, sensitive data removed)
        query_params:
          type: object
          nullable: true
          description: Query parameters
        client_ip:
          type: string
          nullable: true
          description: Client IP address
        user_agent:
          type: string
          nullable: true
          description: User agent string
        error_message:
          type: string
          nullable: true
          description: Error message if request failed
        created_at:
          type: string
          format: date-time
          description: Timestamp when the request was made

    ApiLogsResponse:
      type: object
      description: Paginated API logs response
      properties:
        logs:
          type: array
          items:
            $ref: '#/components/schemas/ApiLog'
          description: Array of log entries
        total:
          type: integer
          description: Total number of logs matching the filters
        limit:
          type: integer
          description: Maximum number of logs per page
        offset:
          type: integer
          description: Number of logs skipped