Developers

Findvice API

Ask Findvice for a Buy, Wait or Avoid decision on a product from your own software or AI assistant. The API is invite-only and is not open yet: a key works only after Findvice has approved a plan for your account.

  • Invite-only
  • Decisions only
  • Beta

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

EndpointPurpose
POST /api/v1/decisionsDecide 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/usageYour limits, the month's total and requests per day.
GET /api/v1/meYour 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.

Back to Findvice