Skip to main content
POST
Search products across every supported retailer and get buyable listings
Beta — the response shape may change without notice while this endpoint is in active development.
POST /agent/search is the agent-native counterpart to Cross-Retailer Search. It returns a single ranked list of buyable products across every supported retailer, and each result’s url can be passed straight to Create MPP Order — no opaque sku id, the URL is the contract. No Zinc account is required. Like the other /agent/* data endpoints, this call is paid per request via the Machine Payments Protocol (MPP): if no valid payment credential is provided, the API returns 402 Payment Required with a WWW-Authenticate challenge for each configured payment method.

Pricing

Use /agent/search to discover orderable URLs, then feed the chosen url directly into POST /agent/orders to buy it — no account, no API key.

Filtering and sorting

POST /agent/search takes the same optional retailer, sort, and limit query parameters as GET /search, and they behave the same way. See Filtering and sorting. A call costs $0.01 whatever limit you set.

402 Payment Required

If no valid payment credential is provided, the API returns 402 Payment Required with one WWW-Authenticate header per payable method (per RFC 9110 §11.6.1). Your MPP client uses these to complete payment and resubmit the request. See the MPP guide for a full walkthrough.

Query Parameters

q
string
required

Search term

min_price
integer | null

Cents. Drop results priced below this.

Required range: x >= 0
max_price
integer | null

Cents. Drop results priced above this. Pass the max_price you intend to send to POST /orders and every result returned fits it. Results with no known price are dropped when a clamp is set.

Required range: x >= 0
retailer
enum<string>[]

Only return results from these retailers. Repeat the param for several: ?retailer=amazon&retailer=target.

Available options:
amazon,
bestbuy,
bhphotovideo,
chewy,
costco,
homedepot,
kohls,
lowes,
macys,
newegg,
staples,
target,
walmart,
wayfair
sort
enum<string>
default:relevance

Result order. relevance (default) blends query match, source rank and rating, and mixes retailers. The explicit sorts order the 20 most relevant results (or limit, if larger) that match at least half the query, so accessories that merely name the product don't lead; results with no price (or no rating, for rating) sort last.

Available options:
relevance,
price_asc,
price_desc,
rating
limit
integer

Return at most this many results (1-50). One search is one billed call either way.

Required range: 1 <= x <= 50

Response

Successful Response

Response from the cross-retailer search endpoint.

status
string
required
query
string
required
results
Sku · object[]
excluded_by_price
integer | null

How many orderable results the min_price/max_price clamp removed; null when no clamp was set.

hint
string | null

Set when the result list is empty for a reason the caller can act on.