---
title: "Searches WEM's catalogue and its connected retailer sources for products matching a query"
method: POST
path: "/api/agent/products/search_products"
---

# Searches WEM's catalogue and its connected retailer sources for products matching a query

`POST /api/agent/products/search_products`

## Request

- Base URL: `https://wem3.ai`
- URL: `https://wem3.ai/api/agent/products/search_products`
- Auth: none declared

Search products by name or identifier (barcode, ASIN, MPN, SKU, WEM ID, wem3.ai/pl URL, or a comma list). catalogMatch gives a held product's offers. Weak matches are withheld and counted in filtered.

## Request body

- object
  - `query` string, required: A product name, or an identifier: barcode (EAN/UPC/GTIN), ASIN, MPN, merchant SKU, WEM ID or wem3.ai/pl URL. Several identifiers may be comma-separated.
  - `category` string: Optional. Keeps only live retailer listings whose own category name matches this text exactly; catalogue matches ignore it. Leave it out unless the shopper names a retailer's category.
  - `min_price` number: Lowest price to include, in `currency`. Applies to retailer listings, not to `catalogMatch`.
  - `max_price` number: Highest price to include, in `currency`. Applies to retailer listings, not to `catalogMatch`.
  - `sort_by` 'relevance' | 'price_asc' | 'price_desc' | 'rating': Order of the live retailer listings (default relevance). Not applied when the query identifies a product.
  - `providers` string[]: Retailer sources to search live, e.g. ["amazon", "awin"]. Omit for all. Catalogue matches are not limited by it.
  - `limit` number: How many listings to request from each retailer source (default 10, max 30). The combined list can hold more.
  - `gtin` string: A product barcode (EAN/UPC/GTIN) the host already has. When given, retailer sources are searched by this barcode instead of by the query words.
  - `currency` string: ISO 4217 code for the shopper's market. Default GBP. Results and price filters use this currency.

## Response `200`

Tool result. `success: false` means the tool ran and reported a problem.

- object
  - `success` boolean, required
  - `data` object: Shape depends on the tool. Search-style results carry `products`, an optional `catalogMatch` of identity-resolved offers, and `filtered`, a count by reason of the weak matches withheld — report that count rather than implying the search was exhaustive.
  - `error` string

## Other responses

- `400`: Unknown tool or a malformed body.
- `429`: Burst or daily quota exhausted. Respect `retry-after` — retrying sooner cannot succeed.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/wem3/apis/wem-price-compare-api.md) · [All operations](https://skmtc.dev/wem3/apis/wem-price-compare-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wem3/apis/wem-price-compare-api/revisions/52e5c33c3f39?raw)