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").
- Автентифікація: заголовок
Authorization: Bearer rv_live_...(API-ключі та scopes)
openapi.json) і подається англійською, як у самому API.Параметри
| Поле | Де | Тип | Обов’язк. | Опис |
|---|---|---|---|---|
idempotency-key | header | string | ні | Makes a retry of this POST safe for 24 hours: the same key and body returns the stored response. |
Тіло запиту
| Поле | Тип | Обов’язк. | Опис |
|---|---|---|---|
vin | string | ні | VIN of the lot (used for the history of this VIN). |
auction | "copart" | "iaai" | "manheim" | "other" | ні | |
lot_id | string | ні | Lot number at the auction. |
make | string | так | |
model | string | так | |
year | integer | так | |
fuel | "petrol" | "diesel" | "hybrid" | "phev" | "ev" | "lpg" | "cng" | "hydrogen" | "other" | так | |
engine_cc | integer | ні | Required for every fuel type except ev. |
kwh | number | ні | Battery capacity; required for ev. |
mileage_km | number | ні | |
title_status | "clean" | "salvage" | "rebuilt" | "flood" | "junk" | "parts_only" | "certificate" | "unknown" | ні | |
damage_primary | string | ні | Primary damage as shown by the auction. |
damage_secondary | string | ні | |
airbags_deployed | boolean | ні | |
runs_and_drives | boolean | ні | |
description | string | ні | Lot description / notes, used for risk flags. |
lot_price_usd | number | так | Current bid or buy-now price in USD. |
auction_yard | string | ні | Yard name, e.g. "NJ - TRENTON". |
us_state | string | ні | |
photos | string (uri)[] | ні | 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" | так | |
destination_city | string | ні | |
target_margin_pct | number | ні | Target margin as a fraction (0.12 = 12%). Default: tenant setting, else 12%. |
date | string | ні | |
arrival_date | string | ні | |
locale | "uk" | "pl" | "en" | ні | |
insurance | "none" | "basic" | "full" | ні | |
audience | "client" | "broker" | ні | "client": no company margin, scenarios or cost of capital. "broker": full report; requires scope write:deals. |
force | boolean | ні | Ignore the VIN+date cache (spends one analysis of the plan quota). |
Відповіді
200
The report.
application/json · Схема: UnderwriteResponse
| Поле | Тип | Обов’язк. | Опис |
|---|---|---|---|
report_id | string (uuid) | так | |
cached | boolean | так | true: a report for the same VIN, date and parameters existed (no quota spent). |
audience | "client" | "broker" | так | |
usage | object | так | |
usage.month | string | так | |
usage.used | integer | так | |
usage.limit | integer | null | так | null: unlimited. |
summary | object | так | |
summary.signal | "green" | "yellow" | "red" | так | |
summary.verdict | string | так | good | ok | risky | no |
summary.currency | string | так | Currency of landed cost / margin figures. |
summary.max_bid_usd | number | null | так | Highest bid (USD) that still meets the target margin; null if none. |
summary.max_bid_conservative_usd | number | null | так | Same with repair at its maximum and resale at p25. null for the client audience. |
summary.repair_usd | object | так | |
summary.landed_total | number | null | так | Turnkey cost including the repair estimate, in currency. null for the client audience. |
summary.margin_pct | number | null | так | Margin at the median resale price (fraction). null for the client audience. |
summary.margin_abs | number | null | так | |
summary.resale_median | number | null | так | Forecast median resale price in currency. null for the client audience. |
summary.flags | object[] | так | |
summary.explanation | string | так | Plain-language explanation in the requested locale. |
summary.warnings | string[] | так | |
summary.typical | object | так | |
summary.vision_mode | string | так | live | mock | none: mock means no ANTHROPIC_API_KEY (demo mode). |
report | object | так | 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 · Схема: Problem
401
Missing, malformed, unknown, revoked or expired API key (code unauthorized).
application/problem+json · Схема: Problem
402
The monthly analysis quota of the plan is used up (code quota_exceeded).
application/problem+json · Схема: Problem
403
The API key lacks the scope required by this endpoint (code insufficient_scope).
application/problem+json · Схема: Problem
422
Not enough data to analyse the lot (e.g. engine_cc missing).
application/problem+json · Схема: Problem
429
Rate limit exceeded for the tenant plan (code rate_limited). Wait Retry-After seconds.
application/problem+json · Схема: Problem
502
FX provider unavailable.
application/problem+json · Схема: Problem