
What you get, and what you do not
Each decision is Findvice's own judgment: Buy, Wait or Avoid, a score, a confidence, the reasons and a recommended action. It never includes store prices, offers, links or catalog rows. Findvice's guidance is informational and not a guarantee. If you show it to your own users, say that it comes from Findvice and that it is not a guarantee.
Authentication and limits
Send your key as Authorization: Bearer <key>. Keys are issued and revoked on your account page. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Monthly-Limit and X-Quota-Monthly-Remaining. Past a limit you get 429 with Retry-After (in seconds). Requests are blocked, never billed, when the monthly allowance is used up.
Endpoints
| Endpoint | Purpose |
|---|---|
POST /api/v1/decisions | Decide for one product. Send at least one of url, query, gtin or modelNumber; optional countryCode, waitingHorizonDays and userContext (targetPriceMinor, maxBudgetMinor). |
GET /api/v1/decisions/{id} | A decision your key created earlier. Other keys' decisions return 404. |
GET /api/v1/usage | Your limits, the month's total and requests per day. |
GET /api/v1/me | Your key's label, limits and usage. |
The machine-readable description is the OpenAPI file.
Example
curl -X POST https://findvice.com/api/v1/decisions \
-H "Authorization: Bearer $FINDVICE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-2026-0001" \
-d '{"query":"Fosi Audio ZA3","countryCode":"US"}'{
"ok": true,
"data": {
"id": "0f6c1c2e-8f7d-4c1a-9d57-2d1f4f0b7a11",
"decision": "WAIT",
"score": 61.5,
"confidence": 0.7,
"currency": "USD",
"product": { "name": "Fosi Audio ZA3", "brand": "Fosi Audio", "modelNumber": "ZA3" },
"recommendedAction": { "type": "WAIT", "message": "Wait for a lower price." },
"reasons": [{ "type": "PRICE_VS_MEDIAN", "explanation": "The price is above the observed median." }],
"analyzedAt": "2026-11-08T12:00:00.000Z",
"engineVersion": "…",
"rulesVersion": "…"
}
}Add an Idempotency-Key (8 to 64 letters, digits, dashes or underscores) to retry safely. The same key with the same request returns the stored decision with Idempotent-Replay: true and no new analysis; the same key with a different request returns 422.
Errors
Failures look like { "ok": false, "error": { "code", "message" } }. Common codes: INVALID_API_KEY (401), API_PLAN_REQUIRED (403), INVALID_DECISION_REQUEST (400), NO_VALID_OFFERS and IDENTITY_MISMATCH (422, the product could not be verified), RATE_LIMITED and MONTHLY_QUOTA_EXCEEDED (429), API_UNAVAILABLE (503, retry).
Use it from an AI assistant (MCP)
Findvice also runs a remote MCP server at https://findvice.com/api/mcp with the tools decide_product, get_decision and get_usage. It uses the same key, limits and decisions-only scope, and each tool call counts as one request. Any signed-in Findvice account can create a key for it under "Connect an AI assistant" on the account page, free to start, with limits that depend on your account and plan. Every decision it returns includes a source field naming Findvice, and the assistant is told to say the answer comes from Findvice. Add it to an MCP-capable assistant like this:
{
"mcpServers": {
"findvice": {
"url": "https://findvice.com/api/mcp",
"headers": { "Authorization": "Bearer YOUR_FINDVICE_API_KEY" }
}
}
}Access and terms
Access is by invitation while the API is being validated. To ask for access, use the API card on the pricing page. The REST API is free for invited users while it is validated; a paid plan is planned at $49.99. Use of the API is also subject to Findvice's Terms and Privacy Policy. Findvice may change limits or end access to protect the service.