IntentLink Shopping Search API

openapi: 3.2.0
info:
  title: Affiliate Recommendation Service Shopping Search API
  version: 0.1.0
tags:
- name: shopping-search
paths:
  /api/v1/shopping/search:
    post:
      tags:
      - shopping-search
      summary: Search
      description: 'Search shopping products and get ranked recommendations. Each result''s ``affiliate_url`` is

        already a ready-to-use trackable buy link (minted + redirect-wrapped inline) — there is no

        separate resolve-link step.'
      operationId: search_api_v1_shopping_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShoppingSearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/shopping/categories:
    get:
      tags:
      - shopping-search
      summary: Categories
      description: 'List the commerce taxonomy (l1/l2/commerce_category + short description) so downstream

        knows the valid values for `commerce_l1s` / `commerce_l2s`. Static per deploy.'
      operationId: categories_api_v1_shopping_categories_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Categories Api V1 Shopping Categories Get
components:
  schemas:
    Coupon:
      properties:
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        requires_manual_entry:
          type: boolean
          title: Requires Manual Entry
          default: false
      type: object
      title: Coupon
    RecommendationResponse:
      properties:
        request_id:
          type: string
          title: Request Id
        status:
          $ref: '#/components/schemas/RecommendationStatus'
        coverage:
          $ref: '#/components/schemas/Coverage'
        normalized_request:
          additionalProperties: true
          type: object
          title: Normalized Request
        attribution:
          anyOf:
          - $ref: '#/components/schemas/Attribution'
          - type: 'null'
        best:
          anyOf:
          - $ref: '#/components/schemas/Offer'
          - type: 'null'
        results:
          items:
            $ref: '#/components/schemas/Offer'
          type: array
          title: Results
        agent_message:
          type: string
          title: Agent Message
        errors:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Errors
        ranking_explanation:
          anyOf:
          - $ref: '#/components/schemas/RankingExplanation'
          - type: 'null'
        from_cache:
          type: boolean
          title: From Cache
          default: false
      type: object
      required:
      - request_id
      - status
      - coverage
      - agent_message
      title: RecommendationResponse
    Offer:
      properties:
        offer_id:
          type: string
          title: Offer Id
        title:
          type: string
          title: Title
        source:
          $ref: '#/components/schemas/SourceSnapshot'
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        effective_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Effective Price
        currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency
        affiliate_url:
          anyOf:
          - type: string
            maxLength: 2083
            minLength: 1
            format: uri
          - type: 'null'
          title: Affiliate Url
        brand:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
        product_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Type
        product_highlight:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Highlight
        product_condition:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Condition
        image_url:
          anyOf:
          - type: string
            maxLength: 2083
            minLength: 1
            format: uri
          - type: 'null'
          title: Image Url
        additional_image_link:
          anyOf:
          - type: string
          - type: 'null'
          title: Additional Image Link
        mobile_url:
          anyOf:
          - type: string
            maxLength: 2083
            minLength: 1
            format: uri
          - type: 'null'
          title: Mobile Url
        price:
          anyOf:
          - type: number
          - type: 'null'
          title: Price
        sale_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Sale Price
        list_price:
          anyOf:
          - type: number
          - type: 'null'
          title: List Price
        discount_amount:
          anyOf:
          - type: number
          - type: 'null'
          title: Discount Amount
        discount_percent:
          anyOf:
          - type: number
          - type: 'null'
          title: Discount Percent
        commission_rate:
          anyOf:
          - type: number
          - type: 'null'
          title: Commission Rate
        rating:
          anyOf:
          - type: number
          - type: 'null'
          title: Rating
        review_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Review Count
        shipping_estimate:
          anyOf:
          - type: number
          - type: 'null'
          title: Shipping Estimate
        tax_estimate:
          anyOf:
          - type: number
          - type: 'null'
          title: Tax Estimate
        availability:
          anyOf:
          - type: string
          - type: 'null'
          title: Availability
        coupon:
          anyOf:
          - $ref: '#/components/schemas/Coupon'
          - type: 'null'
        destination_url:
          anyOf:
          - type: string
            maxLength: 2083
            minLength: 1
            format: uri
          - type: 'null'
          title: Destination Url
        target_country:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Country
        advertiser_country:
          anyOf:
          - type: string
          - type: 'null'
          title: Advertiser Country
        serviceable_areas:
          anyOf:
          - type: string
          - type: 'null'
          title: Serviceable Areas
        link_expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Link Expires At
        price_updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Price Updated At
        score:
          anyOf:
          - type: number
          - type: 'null'
          title: Score
        confidence:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Confidence
          default: 0
        why:
          items:
            type: string
          type: array
          title: Why
        warnings:
          items:
            type: string
          type: array
          title: Warnings
      type: object
      required:
      - offer_id
      - title
      - source
      title: Offer
    Coverage:
      properties:
        claim:
          type: string
          title: Claim
        networks:
          items:
            type: string
          type: array
          title: Networks
        source_count:
          type: integer
          title: Source Count
          default: 0
        offer_count:
          type: integer
          title: Offer Count
          default: 0
        freshness_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Freshness Seconds
        limitations:
          items:
            type: string
          type: array
          title: Limitations
      type: object
      required:
      - claim
      title: Coverage
    Caller:
      properties:
        agent_id:
          type: string
          title: Agent Id
        developer_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Developer Id
        agent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
        agent_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Version
        developer_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Developer Account Id
        app_id:
          anyOf:
          - type: string
          - type: 'null'
          title: App Id
        integration_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Integration Id
      type: object
      required:
      - agent_id
      title: Caller
    TrackingContext:
      properties:
        agent_session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Session Id
        end_user_id_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: End User Id Hash
        sub_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Sub Id
        channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel
      type: object
      title: TrackingContext
    Attribution:
      properties:
        attribution_id:
          type: string
          title: Attribution Id
        click_id:
          type: string
          title: Click Id
        agent_id:
          type: string
          title: Agent Id
        developer_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Developer Id
        developer_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Developer Account Id
        revenue_share_policy_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Revenue Share Policy Id
        settlement_status:
          $ref: '#/components/schemas/SettlementStatus'
          default: pending_click
      type: object
      required:
      - attribution_id
      - click_id
      - agent_id
      title: Attribution
    RankingExplanation:
      properties:
        algorithm:
          type: string
          title: Algorithm
          default: topsis
        active_dimensions:
          items:
            type: string
          type: array
          title: Active Dimensions
        weights:
          additionalProperties:
            type: number
          type: object
          title: Weights
        closeness_score:
          additionalProperties:
            type: number
          type: object
          title: Closeness Score
        per_offer_dim_ranks:
          additionalProperties:
            additionalProperties:
              type: integer
            type: object
          type: object
          title: Per Offer Dim Ranks
      type: object
      title: RankingExplanation
    SourceSnapshot:
      properties:
        network:
          type: string
          title: Network
        upstream_advertiser_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Upstream Advertiser Id
        upstream_advertiser_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Upstream Advertiser Name
        upstream_offer_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Upstream Offer Id
        source_platform:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Platform
      type: object
      required:
      - network
      title: SourceSnapshot
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SettlementStatus:
      type: string
      enum:
      - pending_click
      - pending_conversion
      - eligible
      - rejected
      - paid
      title: SettlementStatus
    ShoppingSearchIntent:
      type: string
      enum:
      - cheapest
      - best_discount
      - top_rated
      - best_value
      title: ShoppingSearchIntent
      description: 'Shopping-specific simplified ranking presets (independent of the legacy ShoppingIntent /

        INTENT_PRESETS used by the old recommender). Each maps to a lean important/secondary profile

        in app.services.shopping_search.ranking. Given a `ranking` object instead, intent is ignored.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ShoppingRankRequest:
      properties:
        important:
          items:
            type: string
          type: array
          title: Important
          description: ~1-2 dims, e.g. ['price']
        secondary:
          items:
            type: string
          type: array
          title: Secondary
          description: ~2-3 supporting dims
        relevance_weight:
          anyOf:
          - type: number
          - type: 'null'
          title: Relevance Weight
        top_n:
          type: integer
          maximum: 50.0
          minimum: 1.0
          title: Top N
          default: 10
        explain_top_k_dims:
          type: integer
          maximum: 10.0
          minimum: 1.0
          title: Explain Top K Dims
          default: 3
      type: object
      title: ShoppingRankRequest
      description: 'Optional fine-grained ranking. Mutually exclusive with ``ShoppingSearchRequest.intent``

        (when present, intent is ignored — see service ⓪). Fill guidance for callers (§5.6):

        ``important`` 1-2 dims, ``secondary`` 2-3; leaving the rest in the low-weight tier.'
    RecommendationStatus:
      type: string
      enum:
      - ok
      - needs_clarification
      - no_results
      - partial_results
      - error
      title: RecommendationStatus
    ShoppingSearchRequest:
      properties:
        query:
          type: string
          minLength: 1
          title: Query
          description: Natural-language intent (semantic).
        keywords:
          items:
            type: string
          type: array
          title: Keywords
          description: 'Exact product terms — brand / model / SPECIFIC product type. Prefer a fully qualified noun phrase (e.g. ''women running shoes'', ''stainless steel knife set'') over a bare generic noun (''shoes'', ''knife''): a generic keyword matches the whole category lexically and can surface the wrong audience (e.g. mens shoes for a girlfriend gift). Audience/occasion context belongs in `query`. Non-empty keywords signal an exact lookup (BM25-leaning ranking).'
        commerce_l1s:
          items:
            type: string
          type: array
          title: Commerce L1S
          description: Optional category L1s.
        commerce_l2s:
          items:
            type: string
          type: array
          title: Commerce L2S
          description: Optional full 'l1.l2' L2s.
        max_price:
          anyOf:
          - type: number
            minimum: 0.0
          - type: 'null'
          title: Max Price
        min_price:
          anyOf:
          - type: number
            minimum: 0.0
          - type: 'null'
          title: Min Price
        in_stock:
          type: boolean
          title: In Stock
          default: true
        platforms:
          items:
            type: string
          type: array
          title: Platforms
          description: Source platforms e.g. amazon/walmart (empty = all).
        require_commission:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Require Commission
          description: Only return products that carry a commission (positive commission_rate). Omit to use the server default.
        country:
          type: string
          title: Country
          default: US
        currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency
        intent:
          anyOf:
          - $ref: '#/components/schemas/ShoppingSearchIntent'
          - type: 'null'
        ranking:
          anyOf:
          - $ref: '#/components/schemas/ShoppingRankRequest'
          - type: 'null'
        caller:
          $ref: '#/components/schemas/Caller'
        tracking:
          $ref: '#/components/schemas/TrackingContext'
        limit:
          type: integer
          maximum: 50.0
          minimum: 1.0
          title: Limit
          default: 10
      type: object
      required:
      - query
      - caller
      title: ShoppingSearchRequest
      description: 'Shopping search request. Only ``query`` is required; the rest narrows recall/filtering.


        ``query`` (semantic) and ``keywords`` (brand/model/exact terms) feed a single combined

        embedding (validated); ``platforms`` selects amazon/walmart (the affiliate network is never

        exposed); ``country`` defaults to US. Ranking is ``intent`` XOR ``ranking``.'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer