API / Search & discovery
Intent in, products out. Ask for “a quiet vacuum for a flat with two cats under $400” and get ranked products with the reasoning attached, so an agent can explain its own recommendation.
POST /v1/search/semantic
| Name | Type | Notes |
|---|---|---|
| intent | string | What the shopper actually wants, in their words. |
| constraints | object | budget_minor, must_have[], avoid[], seller[]. |
| explain | bool | Return a per-result rationale. Default true. |
POST /v1/search/semantic
{ "intent": "quiet vacuum for a small flat with two cats",
"constraints": { "budget_minor": 40000, "must_have": ["hepa"] } }
→ 200
{ "results": [
{ "product_id": "prd_2Ka91x", "title": "Shark Stratos Cordless",
"best": { "seller": "walmart", "price": "$328.00" },
"score": 0.91,
"why": "HEPA sealed, 68 dB rated, pet tool included, 18% under budget",
"verdict": "good" } ] }