POST /v1/underwrite
AI underwriter: repair estimate, risk flags, resale forecast and maximum bid for a lot
AI underwriter: repair estimate, risk flags, resale forecast and maximum bid for a lot
Analyses an auction lot in seconds: Damage Vision over the photos → repair estimate per node (from the tenant price list), risk flags (flood, airbags, odometer rollback, relist, title brands...), resale forecast from the listings cache, landed cost with repair and cost of capital → margin at p25/p50/p75 → the highest bid that still meets the target margin and a green/yellow/red verdict. Scopes: read:pricing AND read:listings. audience "broker" (full report with margin and scenarios) additionally needs write:deals; the default "client" audience never contains the company margin. Quota: Starter/trial 20 analyses per month, Pro 300, Business unlimited; over the limit → 402 quota_exceeded. A repeat call for the same VIN, date and parameters is served from cache and spends nothing. Without ANTHROPIC_API_KEY the vision step runs in demo mode (summary.vision_mode = "mock").
- Authentication: header
Authorization: Bearer rv_live_...(API keys and scopes)
openapi.json).Parameters
| Field | In | Type | Required | Description |
|---|---|---|---|---|
idempotency-key | header | string | no | Makes a retry of this POST safe for 24 hours: the same key and body returns the stored response. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
vin | string | no | VIN of the lot (used for the history of this VIN). |
auction | "copart" | "iaai" | "manheim" | "other" | no | |
lot_id | string | no | Lot number at the auction. |
make | string | yes | |
model | string | yes | |
year | integer | yes | |
fuel | "petrol" | "diesel" | "hybrid" | "phev" | "ev" | "lpg" | "cng" | "hydrogen" | "other" | yes | |
engine_cc | integer | no | Required for every fuel type except ev. |
kwh | number | no | Battery capacity; required for ev. |
mileage_km | number | no | |
title_status | "clean" | "salvage" | "rebuilt" | "flood" | "junk" | "parts_only" | "certificate" | "unknown" | no | |
damage_primary | string | no | Primary damage as shown by the auction. |
damage_secondary | string | no | |
airbags_deployed | boolean | no | |
runs_and_drives | boolean | no | |
description | string | no | Lot description / notes, used for risk flags. |
lot_price_usd | number | yes | Current bid or buy-now price in USD. |
auction_yard | string | no | Yard name, e.g. "NJ - TRENTON". |
us_state | string | no | |
photos | string (uri)[] | no | Public https URLs of lot photos (Damage Vision). Without photos the repair estimate is not made from images. |
destination_country | "UA" | "PL" | "LT" | "GE" | "DE" | yes | |
destination_city | string | no | |
target_margin_pct | number | no | Target margin as a fraction (0.12 = 12%). Default: tenant setting, else 12%. |
date | string | no | |
arrival_date | string | no | |
locale | "uk" | "pl" | "en" | no | |
insurance | "none" | "basic" | "full" | no | |
audience | "client" | "broker" | no | "client": no company margin, scenarios or cost of capital. "broker": full report; requires scope write:deals. |
force | boolean | no | Ignore the VIN+date cache (spends one analysis of the plan quota). |
Responses
200
The report.
application/json · Schema: UnderwriteResponse
| Field | Type | Required | Description |
|---|---|---|---|
report_id | string (uuid) | yes | |
cached | boolean | yes | true: a report for the same VIN, date and parameters existed (no quota spent). |
audience | "client" | "broker" | yes | |
usage | object | yes | |
usage.month | string | yes | |
usage.used | integer | yes | |
usage.limit | integer | null | yes | null: unlimited. |
summary | object | yes | |
summary.signal | "green" | "yellow" | "red" | yes | |
summary.verdict | string | yes | good | ok | risky | no |
summary.currency | string | yes | Currency of landed cost / margin figures. |
summary.max_bid_usd | number | null | yes | Highest bid (USD) that still meets the target margin; null if none. |
summary.max_bid_conservative_usd | number | null | yes | Same with repair at its maximum and resale at p25. null for the client audience. |
summary.repair_usd | object | yes | |
summary.landed_total | number | null | yes | Turnkey cost including the repair estimate, in currency. null for the client audience. |
summary.margin_pct | number | null | yes | Margin at the median resale price (fraction). null for the client audience. |
summary.margin_abs | number | null | yes | |
summary.resale_median | number | null | yes | Forecast median resale price in currency. null for the client audience. |
summary.flags | object[] | yes | |
summary.explanation | string | yes | Plain-language explanation in the requested locale. |
summary.warnings | string[] | yes | |
summary.typical | object | yes | |
summary.vision_mode | string | yes | live | mock | none: mock means no ANTHROPIC_API_KEY (demo mode). |
report | object | yes | The full report (schema version 1): subject, vision, repair, flags, forecast, verdict, explanations, cost, typical, warnings. |
400
Invalid request parameters or body (code validation_error).
application/problem+json · Schema: Problem
401
Missing, malformed, unknown, revoked or expired API key (code unauthorized).
application/problem+json · Schema: Problem
402
The monthly analysis quota of the plan is used up (code quota_exceeded).
application/problem+json · Schema: Problem
403
The API key lacks the scope required by this endpoint (code insufficient_scope).
application/problem+json · Schema: Problem
422
Not enough data to analyse the lot (e.g. engine_cc missing).
application/problem+json · Schema: Problem
429
Rate limit exceeded for the tenant plan (code rate_limited). Wait Retry-After seconds.
application/problem+json · Schema: Problem
502
FX provider unavailable.
application/problem+json · Schema: Problem