Valuation API

Versioned, authenticated and rate limited. It returns exactly what the screen shows — a range, the comparables behind it, the adjustments applied, a legible confidence, days to turn and a buy price. A number without its evidence is not a product, so the API does not offer one.

Request

curl -X POST https://spotlot.io/api/v1/value \
  -H "Authorization: Bearer sk_spotlot_..." \
  -H "Content-Type: application/json" \
  -d '{
    "make": "Ford",
    "model": "Ranger",
    "year": 2019,
    "badge": "XLT",
    "odometer_km": 95000,
    "state": "WA"
  }'

make and model are required; everything else sharpens the comparable set. Keys are issued server-side and stored only as a SHA-256 digest.

Response

{
  "ok": true,
  "valuation_id": "…",
  "model_version": "spotlot-val-0.1.0",
  "range":      { "low": 27558, "mid": 34334, "high": 37888, "currency": "AUD" },
  "confidence": { "score": 0.652, "label": "medium",
                  "parts": { "sample": 0.8, "tightness": 0.0, "recency": 1.0 } },
  "days_to_turn": { "estimate": 41.5, "basis": "…", "n": 18, "cutShare": 0.44 },
  "buy_price":  { "value": 24300, "workings": ["…"] },
  "comparables": [ { "url": "…", "price": 32999, "adjusted_price": 32999,
                     "weight": 1.0, "days_on_market": 12.4, "…": "…" } ],
  "adjustments": [ { "label": "odometer slope", "detail": "…" } ],
  "evidence":    { "comparablesFound": 26, "liveCount": 26, "…": "…" },
  "context":     { "ancap": {…}, "gvg": {…}, "fleet": {…}, "recalls": {…} },
  "quota_remaining_today": 499
}

When the evidence is thin, it says so

{
  "ok": false,
  "reason": "insufficient_comparables",
  "comparables_found": 1,
  "needed": 3
}

Below three comparables the API returns HTTP 200 with ok: false and the real count, rather than a range it cannot support. Callers should treat this as a legitimate answer.

Auth

Authorization: Bearer <key>. Unknown or disabled keys get 401. Keys are stored hashed; the plaintext exists once, at issue time.

Rate limit

A rolling 24-hour quota per key, enforced atomically in Postgres so concurrent calls cannot race past it. Exceeding it returns 429, and every response carries quota_remaining_today.

Corpus behind it

46,027 live listings · 107,940 observations · 7 public datasets joined. Answers are only as good as the coverage, which is why the coverage is on screen.

Why it exists

Spotlot stands alone, and also plugs into other systems as a trade-in data source. This is the socket, built as a real product surface rather than a private integration: versioned path, its own credentials, its own quota. Nothing about it is specific to any one caller.