{"openapi":"3.1.0","info":{"title":"Residual API","description":"Market value estimates for salvage vehicles, from realized auction outcomes. Estimates are not appraisals.","version":"1.0"},"paths":{"/v1/health":{"get":{"summary":"Health","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/form-vocabulary":{"get":{"summary":"Form Vocabulary","description":"The option lists our own lookup form draws from, and their vintage.\n\nKeyless on purpose: the form needs its options before anyone has signed\nin, and these are derived option lists — no listing, no price, no count.\nServing them from the API is what makes scope item 2 true by\nconstruction: there is one artifact, and the surface that renders and the\nsurface that predicts read the same copy of it.\n\nThis is NOT a narrowing of the request contract. `/v1/valuations` accepts\na value that is not in this list exactly as it did before, and puts it\nthrough canonicalization (residual #105); the list constrains what our\nform offers, not what an integrator may send.","operationId":"form_vocabulary_v1_form_vocabulary_get","parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","default":"salvage","title":"Kind"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/subscribe":{"post":{"summary":"Subscribe","operationId":"subscribe_v1_subscribe_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/unsubscribe":{"post":{"summary":"Unsubscribe One Click","description":"RFC 8058 one-click target. Mailbox providers POST here from the\n`List-Unsubscribe-Post` header the digest sets; the body is ignored and\nthe reply is empty, per the RFC.","operationId":"unsubscribe_one_click_v1_unsubscribe_post","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"token","in":"query","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"Unsubscribe","description":"The link a human clicks; token is an HMAC of the address so links\ncan't be forged for other people.","operationId":"unsubscribe_v1_unsubscribe_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"token","in":"query","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/trial":{"post":{"summary":"Create Trial","description":"Self-serve sign-up: a free account with five estimates a month. The\nresponse carries a session (the browser signs in immediately, no email\nround-trip — residual #74) and the key, which only integrators need.\nOne account per email; a handful per IP per day.","operationId":"create_trial_v1_trial_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stripe/webhook":{"post":{"summary":"Stripe Webhook","description":"checkout.session.completed -> upgrade the trial key whose prefix rode in\nclient_reference_id, and attach the Stripe customer for metering.","operationId":"stripe_webhook_v1_stripe_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/link":{"post":{"summary":"Auth Link","operationId":"auth_link_v1_auth_link_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/session":{"post":{"summary":"Auth Session","operationId":"auth_session_v1_auth_session_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/logout":{"post":{"summary":"Auth Logout","operationId":"auth_logout_v1_auth_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/account":{"get":{"summary":"Account Overview","operationId":"account_overview_v1_account_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/account/users":{"post":{"summary":"Account Add User","description":"Add a named seat (admin only). The person signs in with their own\nemail; nothing is shared (residual #137).","operationId":"account_add_user_v1_account_users_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/users/remove":{"post":{"summary":"Account Remove User","operationId":"account_remove_user_v1_account_users_remove_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/keys":{"post":{"summary":"Account Create Key","operationId":"account_create_key_v1_account_keys_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/billing-portal":{"post":{"summary":"Account Billing Portal","operationId":"account_billing_portal_v1_account_billing_portal_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/account/keys/revoke":{"post":{"summary":"Account Revoke Key","operationId":"account_revoke_key_v1_account_keys_revoke_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/model":{"get":{"summary":"Model Info","operationId":"model_info_v1_model_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/valuations":{"post":{"summary":"Create Valuation","operationId":"create_valuation_v1_valuations_post","parameters":[{"name":"X-Lookup","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Lookup"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Session","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Session"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/history":{"get":{"summary":"Vehicle History","operationId":"vehicle_history_v1_history_get","parameters":[{"name":"vin","in":"query","required":true,"schema":{"type":"string","title":"Vin"}},{"name":"declared_title","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Declared Title"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/collateral":{"post":{"summary":"Collateral Report","operationId":"collateral_report_v1_collateral_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollateralRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/acv":{"post":{"summary":"Acv Estimate","description":"Retail market value — a different model on a different market from\n`/v1/valuations`, not a variant of it. Refuses rather than extrapolates\noutside the retail fleet it was fit on.\n\nBoth doors, like `/v1/valuations`: the report page asks for retail\nbeside the salvage number with whichever credential it just valued with,\nand a signed-in reader has a session, never a key (residual #151).","operationId":"acv_estimate_v1_acv_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Session","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Session"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ACVRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ACVResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/demo":{"post":{"summary":"Demo Valuation","description":"Keyless tryout: the real model and the real number, on the free rung of\nthe content ladder (residual #78) — the estimate, its range and the n and\nwindow behind it, without the comparable sales. Metered by\n`demo_limit` per LOOKUP, not per call: the form regenerates at every\nanswer (residual #193), so a continued demo lookup does not charge the\nmeter again — within the bounds `lookups` sets on keyless ones. Logged\nunder the reserved 'public-demo' key row.","operationId":"demo_valuation_v1_demo_post","parameters":[{"name":"X-Device","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Device"}},{"name":"X-Lookup","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Lookup"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ACVBand":{"properties":{"low":{"type":"number","title":"Low"},"high":{"type":"number","title":"High"},"quantiles":{"items":{"type":"string"},"type":"array","title":"Quantiles"},"nominal_coverage":{"type":"number","title":"Nominal Coverage"},"measured_coverage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Measured Coverage","description":"Empirical coverage of this band on the artifact's held-out slice; null when the artifact does not attest it"},"measured_n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Measured N","description":"Rows the coverage was measured over"},"measured_median_width_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Measured Median Width Usd"},"measured_median_rel_width":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Measured Median Rel Width","description":"Median band width as a share of p50"},"worst_cohort":{"anyOf":[{"$ref":"#/components/schemas/ACVCohort"},{"type":"null"}]}},"type":"object","required":["low","high","quantiles","nominal_coverage"],"title":"ACVBand"},"ACVBasis":{"properties":{"artifact":{"type":"string","title":"Artifact"},"vintage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vintage"},"verified_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verified At"},"n_test":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N Test"},"n_settled":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N Settled"},"n_calibration":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N Calibration"},"label_window":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label Window","description":"Sale-date span the attestation was measured over"},"settled_median_sale_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Settled Median Sale Date","description":"Median sale date of the settled slice. Stated beside the window because settlement is right-censored, so the slice is back-weighted within it"},"split_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Split Mode","description":"`random` means the attestation is in-period: the holdout is drawn from the weeks the head was fit on, not from after them"},"quantiles":{"items":{"type":"string"},"type":"array","title":"Quantiles"},"calibration_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calibration Method"},"vocab_fold_rule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vocab Fold Rule","description":"How an ambiguous casing resolves onto a frozen vocab level: `train-mass` or `lowest-index`"},"fleet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fleet","description":"The retail sales the model was fit on — age, mileage and price — in the artifact's own words"},"caveats":{"items":{"type":"string"},"type":"array","title":"Caveats","description":"Attested weaknesses no query can be routed around, so stated rather than refused"}},"type":"object","required":["artifact","quantiles"],"title":"ACVBasis"},"ACVCohort":{"properties":{"cohort":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cohort"},"n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N"},"coverage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Coverage"},"slice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slice","description":"Which attested slice the cell comes from — `settled` is the serving-facing read"}},"type":"object","title":"ACVCohort","description":"The worst cohort this band's coverage was attested over. It travels\nwith the pooled number because residual #100's floors bind the worst\ncohort, not the pool."},"ACVRequest":{"properties":{"vin":{"anyOf":[{"type":"string","maxLength":17,"minLength":11},{"type":"null"}],"title":"Vin","description":"Decoded via cached NHTSA vPIC; also the only source of `base_price` (vPIC BasePrice)"},"year":{"anyOf":[{"type":"integer","maximum":2030.0,"minimum":1900.0},{"type":"null"}],"title":"Year"},"make":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Make"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"trim":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trim"},"odometer":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Odometer","description":"Mileage"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"Two-letter US state"},"body_style":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Style"},"fuel_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fuel Type"},"drive_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Drive Type"},"transmission":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transmission"},"engine_hp":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Engine Hp"},"displacement_l":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Displacement L"},"engine_cylinders":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Engine Cylinders"},"base_price":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Base Price","description":"Original base MSRP, USD. Filled from the VIN decode when not supplied"}},"additionalProperties":false,"type":"object","title":"ACVRequest","description":"Subject for a retail market value estimate. A strict subset of\n`ValuationRequest`: the retail head is fit on listed no-haggle retail\ncars, so none of the salvage lot context (damage, title, auction branch)\nis a feature of it, and a field it does not declare is dropped rather\nthan passed through."},"ACVResponse":{"properties":{"subject":{"additionalProperties":true,"type":"object","title":"Subject"},"estimate":{"type":"number","title":"Estimate","description":"Retail market value estimate, USD; equals p50 by construction"},"currency":{"type":"string","title":"Currency","default":"USD"},"quantiles":{"additionalProperties":{"type":"number"},"type":"object","title":"Quantiles","description":"Full calibrated quantile vector, USD"},"interval":{"additionalProperties":{"type":"number"},"type":"object","title":"Interval","description":"p10/p50/p90 transition shape, kept so a caller reading `/v1/valuations` reads this the same way"},"bands":{"additionalProperties":{"$ref":"#/components/schemas/ACVBand"},"type":"object","title":"Bands","description":"Nested bands: inner p25-p75, mid p10-p90, outer p5-p95, each with its nominal and measured coverage"},"basis":{"$ref":"#/components/schemas/ACVBasis"},"basis_note":{"type":"string","title":"Basis Note"},"in_support":{"type":"boolean","title":"In Support","description":"Always true on a served response — an out-of-fleet subject is refused, never extrapolated onto"},"quota_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quota Note","description":"Present when a paid account is past its plan's monthly vehicles — retail shares that meter (residual #147), so it carries the same note `/v1/valuations` does. Null otherwise"},"model":{"$ref":"#/components/schemas/ModelInfo"},"disclaimer":{"type":"string","title":"Disclaimer"}},"type":"object","required":["subject","estimate","quantiles","interval","bands","basis","basis_note","in_support","model","disclaimer"],"title":"ACVResponse"},"BandCalibration":{"properties":{"profile":{"type":"string","title":"Profile","description":"The registered calibration profile that produced this response's band — resolved from the supplied inputs"},"cohort_n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cohort N"},"cohort_window":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cohort Window"},"n_calibration":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N Calibration"},"target_coverage":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}],"title":"Target Coverage"}},"type":"object","required":["profile"],"title":"BandCalibration"},"CollateralRequest":{"properties":{"vin":{"anyOf":[{"type":"string","maxLength":17,"minLength":11},{"type":"null"}],"title":"Vin","description":"Decoded via cached NHTSA vPIC"},"year":{"anyOf":[{"type":"integer","maximum":2030.0,"minimum":1900.0},{"type":"null"}],"title":"Year"},"make":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Make"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"trim":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trim"},"odometer":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Odometer"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"Two-letter US state"}},"additionalProperties":false,"type":"object","title":"CollateralRequest","description":"Subject identity for a collateral report: a running, clean-title\nvehicle — so no lot/damage context here by design (collateral.py owns\nthe floor-scenario convention)."},"Comp":{"properties":{"year":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Year"},"make":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Make"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"trim":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trim"},"primary_damage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Damage"},"title_group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title Group"},"odometer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Odometer"},"sale_date":{"type":"string","title":"Sale Date"},"realized_price":{"type":"number","title":"Realized Price"},"similarity":{"type":"number","title":"Similarity","description":"Retrieval-space score, ordering only. Prefer `match_reason`, which states what the row shares with the subject in the row's own terms.","deprecated":true},"match_reason":{"anyOf":[{"items":{"$ref":"#/components/schemas/MatchChip"},"type":"array"},{"type":"null"}],"title":"Match Reason","description":"Why this row is comparable: the facts the subject and this comp both carry, in priority order, capped at three plus recency. A chip is minted only when both sides carry the fact, so a sparse query yields fewer chips rather than a guess. Null when the serving bundle carries no chip rules."},"same_model_recent":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Same Model Recent","description":"True when this comp carries the subject's make and model and its model year is within 3 of the subject's, inclusive. A missing value on either side is never a match. Computed on the full rule set, not on the chips: `match_reason` is capped at three facts plus recency, so a row inside this flag can carry no year chip — count the flag, never the chips. Whether two spellings of a model are the same model is decided by the serving bundle's identity rule, and this field is the only place that decision is published: re-deriving it from `make`/`model`/`year` can disagree with the chips drawn beside it. Null when the serving bundle computes no flags — null is not false."},"vehicle_class":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vehicle Class","description":"Derived coarse class (passenger vehicle, motorcycle, commercial truck, rv/trailer, marine); null if the source lot carried no class signal and its make/model is not in the body-type map"},"body_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Type","description":"Finer body tier (pickup, suv, sedan, coupe, hatchback, wagon, van, convertible, truck, bus, motorcycle, atv, trailer, rv, boat). Taken from the source lot's body style when it carries one, else the modal body style observed for that make/model; null when neither is available"}},"type":"object","required":["sale_date","realized_price","similarity"],"title":"Comp"},"CompWindow":{"properties":{"oldest_sale_date":{"type":"string","title":"Oldest Sale Date"},"newest_sale_date":{"type":"string","title":"Newest Sale Date"},"span_days":{"type":"integer","title":"Span Days","description":"newest_sale_date - oldest_sale_date, in days: the spread of the attended neighbors, anchored to nothing"},"recency_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Recency Days","description":"Request date - oldest_sale_date, in days: how far back the attended neighbors reach from the moment the question was asked. This is the number the 'spanning the last w days' copy states. Null when the dates cannot carry it (residual #146)."}},"type":"object","required":["oldest_sale_date","newest_sale_date","span_days"],"title":"CompWindow"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Interval":{"properties":{"p10":{"type":"number","title":"P10"},"p50":{"type":"number","title":"P50"},"p90":{"type":"number","title":"P90"}},"type":"object","required":["p10","p50","p90"],"title":"Interval"},"MatchChip":{"properties":{"key":{"type":"string","title":"Key","description":"Stable rule id: model, class, damage, odometer, year, title, location, state, recency"},"text":{"type":"string","title":"Text","description":"The fact, as displayed"}},"type":"object","required":["key","text"],"title":"MatchChip","description":"One checkable fact the subject and this comp share (cargo #24).\n\n`text` is display copy about the row it sits on (\"same damage type\",\n\"odometer within 8K mi\"); `key` is the stable rule id to render or filter\non, since the wording is data in the bundle and can be reworded without a\nschema change. Numeric bands round away from the subject, so the claim is\nnever smaller than the true gap."},"ModelInfo":{"properties":{"tag":{"type":"string","title":"Tag"},"trained_through":{"type":"string","title":"Trained Through"},"version_id":{"type":"string","title":"Version Id"}},"type":"object","required":["tag","trained_through","version_id"],"title":"ModelInfo"},"Quantiles":{"properties":{"p5":{"type":"number","title":"P5"},"p10":{"type":"number","title":"P10"},"p25":{"type":"number","title":"P25"},"p50":{"type":"number","title":"P50"},"p75":{"type":"number","title":"P75"},"p90":{"type":"number","title":"P90"},"p95":{"type":"number","title":"P95"}},"type":"object","required":["p5","p10","p25","p50","p75","p90","p95"],"title":"Quantiles"},"RecordedSales":{"properties":{"window_end":{"type":"string","title":"Window End","description":"Last sale date any window includes: the serving bundle's data cutoff"},"levels":{"items":{"$ref":"#/components/schemas/RecordedSalesLevel"},"type":"array","title":"Levels","description":"Year/make/model first, then one level per further answer, each narrower than the last. Counts and medians only — the calibrated band is the range"}},"type":"object","required":["window_end","levels"],"title":"RecordedSales"},"RecordedSalesLevel":{"properties":{"matched_on":{"items":{"type":"string"},"type":"array","title":"Matched On","description":"The request fields this level matched exactly, in the order the lookup asks them; `odometer` matches within 20,000 mi"},"n":{"type":"integer","title":"N","description":"Recorded sales matching, over `window_days`"},"median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median","description":"Median realized price of those sales, USD; null below the minimum count a median is printed on"},"window_days":{"type":"integer","title":"Window Days","description":"90, or 180 when fewer than the minimum count sold in 90 days and 180 holds enough"},"window_start":{"type":"string","title":"Window Start","description":"First sale date the window includes (ISO date)"}},"type":"object","required":["matched_on","n","window_days","window_start"],"title":"RecordedSalesLevel"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ValuationRequest":{"properties":{"vin":{"anyOf":[{"type":"string","maxLength":17,"minLength":11},{"type":"null"}],"title":"Vin","description":"Decoded via cached NHTSA vPIC to fill vehicle identity/specs"},"year":{"anyOf":[{"type":"integer","maximum":2030.0,"minimum":1900.0},{"type":"null"}],"title":"Year"},"make":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Make"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"trim":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trim"},"odometer":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Odometer"},"primary_damage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Damage","description":"e.g. Front End, Side, Water/Flood — see GET /v1/form-vocabulary for the served values"},"secondary_damage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Secondary Damage","description":"see GET /v1/form-vocabulary"},"title_group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title Group","description":"SALVAGE TITLE, CLEAN TITLE, NON-REPAIRABLE — see GET /v1/form-vocabulary. The short forms 'clean'/'salvage' are synonyms, not levels"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"Two-letter US state of sale/location"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Ignored. Estimates are quoted on a Copart basis; see the `basis` field on the response.","deprecated":true},"fuel_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fuel Type"},"drive_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Drive Type"},"transmission":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transmission"},"color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Color"},"has_keys":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Keys"},"acv_estimate":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Acv Estimate","description":"Insurer/auction estimated pre-loss value, USD"},"retail_estimate":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Retail Estimate","description":"Auction 'estimated retail value', USD"},"repair_cost":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Repair Cost","description":"Estimated repair cost, USD"},"insurance_value":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Insurance Value"},"auction_location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auction Location","description":"e.g. TX - DALLAS"},"sale_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sale Type"},"condition_grade":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Condition Grade","description":"e.g. Run & Drive, Stationary — see GET /v1/form-vocabulary"},"engine":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Engine","description":"Raw engine string, e.g. '2.5L 4'"},"body_style":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Style"},"engine_hp":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Engine Hp"},"displacement_l":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Displacement L"},"engine_cylinders":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Engine Cylinders"}},"additionalProperties":false,"type":"object","title":"ValuationRequest","description":"Subject-vehicle fields. Everything is optional except enough identity to\nvalue against (VIN, or year+make+model); missing fields are handled by the\nmodel's null-masking, but each one supplied improves the estimate."},"ValuationResponse":{"properties":{"estimate":{"type":"number","title":"Estimate","description":"Point estimate of realized hammer price, USD; equals the median (p50) by construction"},"currency":{"type":"string","title":"Currency","default":"USD"},"interval":{"anyOf":[{"$ref":"#/components/schemas/Interval"},{"type":"null"}],"description":"p10/p50/p90 range, conformal-calibrated; null when the serving bundle has no quantile head. Retained for compatibility — prefer `quantiles`"},"quantiles":{"anyOf":[{"$ref":"#/components/schemas/Quantiles"},{"type":"null"}],"description":"Full calibrated quantile vector in USD; null when the serving bundle exposes only p10/p50/p90. Band semantics: inner 50% = p25-p75, outer 90% = p5-p95, per-cohort conformal-calibrated"},"band_calibration":{"anyOf":[{"$ref":"#/components/schemas/BandCalibration"},{"type":"null"}],"description":"Which registered calibration profile produced the band, with the cohort n and window it was fit on — sparse payloads resolve to a profile fit for that sparsity (residual #144). Null when the band came from the pooled calibration. Honesty furniture: identical at every tier, like the band itself"},"n_comparables":{"type":"integer","title":"N Comparables","description":"Size of the neighbor set the estimate attends to. A paid tier receives one `comps` row per attended neighbor, so `len(comps) == n_comparables`; free tiers receive none and say so in `content_note`"},"comp_window":{"anyOf":[{"$ref":"#/components/schemas/CompWindow"},{"type":"null"}],"description":"Sale-date span of the full attended neighbor set (all n_comparables); null when the serving bundle does not report it. Neighbors are top-k by similarity, not time-boxed"},"comps":{"items":{"$ref":"#/components/schemas/Comp"},"type":"array","title":"Comps","description":"The attended neighbors this tier receives, ranked: same vehicle class first, then same make, and most similar first within each of those tiers. A paid tier receives all `n_comparables` of them; a narrower tier is a view of this same ordering — its first rows, never a different selection — and free tiers receive none. Ranking is display-only: the estimate attends the full neighbor set and does not depend on it. The count is the model's k, not a page size; there is no parameter to ask for more or fewer"},"subject_class":{"type":"string","title":"Subject Class","description":"Derived coarse class of the subject"},"subject_body_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject Body Type","description":"Derived body tier of the subject; null when the supplied identity does not resolve to one"},"comp_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comp Note","description":"Present when the comps returned include off-type or unclassified vehicles; both are labeled, not hidden. Counts the rows it is sent with"},"recorded_sales":{"anyOf":[{"$ref":"#/components/schemas/RecordedSales"},{"type":"null"}],"description":"Recorded sales like the subject: how many sold and their median, at each level of the answers given (residual #193). Substantiation beside the estimate, identical at every tier. Null when the serving bundle's pool is not indexed"},"input_tier":{"type":"string","title":"Input Tier","description":"'listing-grade' when valuation-context fields were supplied, else 'identity-only'"},"content_tier":{"type":"string","title":"Content Tier","description":"Which rung of the content ladder this payload is: 'estimate' (free — the number, its calibrated range and the n/window it was measured on) or 'report' (paid — the same number with the comparable sales attached). The estimate, the range and the honesty furniture are identical at every tier; only attachments move","default":"report"},"content_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Note","description":"Present when the tier withholds an attachment, naming what is withheld. Null on a full payload"},"quota_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quota Note","description":"Present when a paid account is past its plan's monthly vehicles: the request was served in full and no overage is ever billed — this names the state and where the next tier is. Null otherwise"},"lookup_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lookup Token","description":"Send this back as the `X-Lookup` header to re-value the same vehicle as answers are added or corrected: every run in one lookup counts as one vehicle. A request that resolves to a different year, make, model or VIN is refused with 409 — start a new lookup (no header) for another vehicle"},"accuracy_note":{"type":"string","title":"Accuracy Note"},"basis":{"type":"string","title":"Basis","description":"The measurement basis the number is quoted on: realized Copart salvage-auction outcomes, with the auction house asserted rather than taken as an input"},"model":{"$ref":"#/components/schemas/ModelInfo"},"disclaimer":{"type":"string","title":"Disclaimer"}},"type":"object","required":["estimate","n_comparables","comps","subject_class","input_tier","accuracy_note","basis","model","disclaimer"],"title":"ValuationResponse"}}}}