---
title: "Search Recommendations"
method: POST
path: "/api/v1/recommendations/search"
tags: ["recommendations"]
---

# Search Recommendations

`POST /api/v1/recommendations/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/recommendations/search`
- Auth: none declared

## Request body

- RecommendationSearchRequest
  - `product_name` string, required
  - `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
  - `raw_user_query` string, nullable
  - `intent` 'cheapest' | 'best_discount' | 'best_value' | 'fastest_delivery'
  - `market` Market
    - `country` string, nullable
    - `currency` string, nullable
    - `language` string, nullable
  - `product` ProductConstraints
    - `brand` string, nullable
    - `category` string, nullable
    - `keywords` string[]
    - `model` string, nullable
    - `color` string, nullable
    - `gender` string, nullable
  - `constraints` SearchConstraints
    - `max_price` number, nullable
    - `must_be_in_stock` boolean
    - `allow_refurbished` boolean
    - `allowed_sources` string[]
    - `excluded_sources` string[]
    - `min_confidence` number
    - `max_results` integer
  - `tracking` TrackingContext
    - `agent_session_id` string, nullable
    - `end_user_id_hash` string, nullable
    - `sub_id` string, nullable
    - `channel` string, nullable
  - `ranking` RankRequest
    - `algorithm` 'topsis'
    - `priority` PriorityProfile
      - `important` string[]
      - `secondary` string[]
      - `irrelevant` string[]
      - `tier_coefficients` object
      - `intra_tier_distribution` 'equal' | 'rank_decay'
    - `top_n` integer
    - `explain_top_k_dims` integer
    - `use_intent_preset` boolean

## 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)