API / Decisioning & equivalence
Intent and constraints in, a ranked recommendation out — with the reasoning, the runner-up, and what would change the answer. Built to be shown to a user, not just consumed.
POST /v1/decide
| Name | Type | Notes |
|---|---|---|
| intent | string | What the buyer is trying to achieve, in their words. |
| candidates | string[] | Optional. Omit and it searches. |
| constraints | object | budget_minor, deliver_by, destination, must_have[], avoid[]. |
| weights | object | price, speed, quality, trust. Defaults to balanced. |
| namespace | string | Optional memory namespace, so prior constraints apply automatically. |
POST /v1/decide
{ "intent": "headphones for a long-haul flight next Tuesday",
"constraints": { "budget_minor": 30000, "deliver_by": "2026-09-12",
"destination": { "postal_code": "10001", "country": "US" } },
"weights": { "price": 0.3, "speed": 0.4, "quality": 0.3 },
"namespace": "user_9f21" }
→ 200
{ "recommendation": {
"product_id": "prd_8Fk2xQ", "title": "Sony WH-1000XM5",
"offer": { "seller": "bestbuy", "price": "$198.00",
"landed": "$198.00", "delivers_by": "2026-09-10" },
"why": [
"Arrives 2 days before the deadline; the cheaper Walmart offer does not.",
"$198.00 is the 4th percentile of its own 89-day history — a genuine low, not a reference-price discount.",
"Memory: this buyer rejected on-ear designs in March." ],
"confidence": 0.88 },
"runner_up": {
"product_id": "prd_4a91xB", "title": "Bose QuietComfort Ultra",
"why_not": "Arrives 2026-09-13, one day past the deadline." },
"would_change_if": [
{ "condition": "deadline moved past 2026-09-14",
"then": "Bose QuietComfort Ultra — better comfort rating for a long flight" },
{ "condition": "budget raised above $349",
"then": "AirPods Max 2 — strongest ANC in the set" } ],
"considered": 14 }`would_change_if` exists because agents get overridden. When a user pushes back, the agent needs to know which constraint was binding rather than starting the search again.
Passing a memory `namespace` applies stored constraints automatically, so a buyer who told you in March that they will not buy on-ear does not have to say it again.
This endpoint composes search, equivalence, price context and fulfilment. It is metered accordingly — it is the most expensive call in the API and usually replaces six.