Skip to main content
The product search endpoint queries the affiliate product catalog using natural language and structured filters. Results are paginated with opaque cursors and include pricing, merchant, and availability data.

​
Endpoint

POST /v1/discovery/products/search
Requires an x-api-key header.

​
Request Body (AffiliateDiscoverySearchRequest)

​
query
string
Free-text search query, e.g. "running shoes". Required for initial searches; omit when paginating with a cursor.
​
criteria_set_ids
string[]
Array of saved criteria set IDs to apply to this search.
​
exclude_query
string
Negative keyword filter applied to name, description, and brand fields.
​
criteria
object[]
Array of structured filter criteria. Each criterion has field, operator, and value.
​
per_page
integer
Number of results per page. Min: 1, Max: 100. Default: 25.
​
cursor
string
Opaque cursor from a previous search response for pagination. When using a cursor, omit all other fields.

​
Example Request

curl -X POST https://rewardsbot-prod.liquidrewardsapi.com/v1/discovery/products/search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "running shoes",
    "criteria": [
      { "field": "on_sale", "operator": "=", "value": true },
      { "field": "in_stock", "operator": "=", "value": true },
      { "field": "final_price", "operator": "<=", "value": 100.00 }
    ],
    "per_page": 25
  }'

​
Response (AffiliateDiscoverySearchResponse)

​
query
string
The interpreted query string.
​
page_index
integer
Current page index.
​
page_size
integer
Number of items on this page.
​
items
AffiliateDiscoverySearchItem[]
Array of matching products.
​
next_cursor
string | null
Cursor for the next page. null when no more results remain.
​
expires_at
string | null
ISO 8601 timestamp after which this result set expires.

​
Error Responses

Status CodeDescription
403 ForbiddenMissing API key
404 Not FoundCursor or backing ranking session not found
410 GoneCursor or backing ranking session has expired
416 Range Not SatisfiableCursor page is out of range
503 Service UnavailableAffiliate discovery is not configured
422 Unprocessable EntityValidation error