--- title: "Search" method: POST path: "/api/v1/shopping/search" tags: ["shopping-search"] --- # Search `POST /api/v1/shopping/search` ## Request - Base URL: `https://api.intentlink.io` (the document declares no server; this is the origin it was published from) - URL: `https://api.intentlink.io/api/v1/shopping/search` - Auth: none declared 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. ## Request body - ShoppingSearchRequest: 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``. - `query` string, required: Natural-language intent (semantic). - `keywords` string[]: 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` string[]: Optional category L1s. - `commerce_l2s` string[]: Optional full 'l1.l2' L2s. - `max_price` number, nullable - `min_price` number, nullable - `in_stock` boolean - `platforms` string[]: Source platforms e.g. amazon/walmart (empty = all). - `require_commission` boolean, nullable: Only return products that carry a commission (positive commission_rate). Omit to use the server default. - `country` string - `currency` string, nullable - `intent` 'cheapest' | 'best_discount' | 'top_rated' | 'best_value': 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. - `ranking` ShoppingRankRequest: 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. - `important` string[]: ~1-2 dims, e.g. ['price'] - `secondary` string[]: ~2-3 supporting dims - `relevance_weight` number, nullable - `top_n` integer - `explain_top_k_dims` integer - `caller` Caller, required - `agent_id` string, required - `developer_id` string, nullable - `agent_name` string, nullable - `agent_version` string, nullable - `developer_account_id` string, nullable - `app_id` string, nullable - `integration_id` string, nullable - `tracking` TrackingContext - `agent_session_id` string, nullable - `end_user_id_hash` string, nullable - `sub_id` string, nullable - `channel` string, nullable - `limit` integer ## Response `200` Successful Response - RecommendationResponse - `request_id` string, required - `status` 'ok' | 'needs_clarification' | 'no_results' | 'partial_results' | 'error', required - `coverage` Coverage, required - `claim` string, required - `networks` string[] - `source_count` integer - `offer_count` integer - `freshness_seconds` integer, nullable - `limitations` string[] - `normalized_request` object - `attribution` Attribution - `attribution_id` string, required - `click_id` string, required - `agent_id` string, required - `developer_id` string, nullable - `developer_account_id` string, nullable - `revenue_share_policy_id` string, nullable - `settlement_status` 'pending_click' | 'pending_conversion' | 'eligible' | 'rejected' | 'paid' - `best` Offer - `offer_id` string, required - `title` string, required - `source` SourceSnapshot, required - `network` string, required - `upstream_advertiser_id` string, nullable - `upstream_advertiser_name` string, nullable - `upstream_offer_id` string, nullable - `source_platform` string, nullable - `description` string, nullable - `effective_price` number, nullable - `currency` string, nullable - `affiliate_url` string, uri, nullable - `brand` string, nullable - `category` string, nullable - `product_type` string, nullable - `product_highlight` string, nullable - `product_condition` string, nullable - `image_url` string, uri, nullable - `additional_image_link` string, nullable - `mobile_url` string, uri, nullable - `price` number, nullable - `sale_price` number, nullable - `list_price` number, nullable - `discount_amount` number, nullable - `discount_percent` number, nullable - `commission_rate` number, nullable - `rating` number, nullable - `review_count` integer, nullable - `shipping_estimate` number, nullable - `tax_estimate` number, nullable - `availability` string, nullable - `coupon` Coupon - `code` string, nullable - `description` string, nullable - `expires_at` string, date-time, nullable - `requires_manual_entry` boolean - `destination_url` string, uri, nullable - `target_country` string, nullable - `advertiser_country` string, nullable - `serviceable_areas` string, nullable - `link_expires_at` string, date-time, nullable - `price_updated_at` string, date-time, nullable - `score` number, nullable - `confidence` number - `why` string[] - `warnings` string[] - `results` Offer[] - `offer_id` string, required - `title` string, required - `source` SourceSnapshot, required - `network` string, required - `upstream_advertiser_id` string, nullable - `upstream_advertiser_name` string, nullable - `upstream_offer_id` string, nullable - `source_platform` string, nullable - `description` string, nullable - `effective_price` number, nullable - `currency` string, nullable - `affiliate_url` string, uri, nullable - `brand` string, nullable - `category` string, nullable - `product_type` string, nullable - `product_highlight` string, nullable - `product_condition` string, nullable - `image_url` string, uri, nullable - `additional_image_link` string, nullable - `mobile_url` string, uri, nullable - `price` number, nullable - `sale_price` number, nullable - `list_price` number, nullable - `discount_amount` number, nullable - `discount_percent` number, nullable - `commission_rate` number, nullable - `rating` number, nullable - `review_count` integer, nullable - `shipping_estimate` number, nullable - `tax_estimate` number, nullable - `availability` string, nullable - `coupon` Coupon - `code` string, nullable - `description` string, nullable - `expires_at` string, date-time, nullable - `requires_manual_entry` boolean - `destination_url` string, uri, nullable - `target_country` string, nullable - `advertiser_country` string, nullable - `serviceable_areas` string, nullable - `link_expires_at` string, date-time, nullable - `price_updated_at` string, date-time, nullable - `score` number, nullable - `confidence` number - `why` string[] - `warnings` string[] - `agent_message` string, required - `errors` object[] - `ranking_explanation` RankingExplanation - `algorithm` string - `active_dimensions` string[] - `weights` object - `closeness_score` object - `per_offer_dim_ranks` object - `from_cache` boolean ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/intentlink/apis/affiliate-recommendation-service.md) · [All operations](https://skmtc.dev/intentlink/apis/affiliate-recommendation-service/llms.txt) · [OpenAPI document](https://skmtc.dev/intentlink/apis/affiliate-recommendation-service/revisions/95cc11d55fb6?raw)