{ "openapi": "3.1.0", "info": { "title": "MotorsDynamic API v2", "version": "2.0.0-alpha.1", "summary": "Dealer inventory, VIN history, change feeds, market prices and OEM offers.", "description": "Read API for MotorsDynamic dealer data. `/v1` (`/api/*`, `/api/v1/*`) is frozen and unchanged;\nthis is a separate, additive contract served at `/api/v2`.\n\n**Authentication.** `X-API-Key: ` (or a dashboard session `Authorization: Bearer `).\n\n**Entitlement.** Every route is limited to the sites (rooftops) your agency may read: sites the\nagency owns in MotorsDynamic, its dealers and tracked competitors, and sites it registered with\n`POST /api/v2/dealers`. A request for another site returns `403 not_entitled`.\n\n**Pagination.** Lists return `page.next_cursor`. Pass it back unchanged as `cursor` with the same\nfilters; `has_more: false` means the walk is complete. Cursors are keyset positions on\n`(sort key, id)`, so a walk returns every row exactly once even when many rows share a sort value\nand while inventory changes underneath. A cursor used with different filters returns\n`400 cursor_mismatch`.\n\n**Freshness and provenance.** Every item has a `freshness` block (`last_seen_at`: when the listing\nwas last seen on the dealer site; `observed_at`: when that observation was made) and a\n`provenance` block (`source`: `v2` for the new crawler, `md_legacy` for the legacy pipeline and its\narchive, `foureyes` for the imported Foureyes history).\n\n**Per-VIN endpoints.** `/vin/{vin}`, `/listings/{vin}`, `/photos/{vin}`, `/build/{vin}`, `/specs/{vin}`,\n`/history/{vin}`, `/recalls/{vin}`, `/complaints/{vin}`, `/safety/{vin}`, `/fuel/{vin}`, `/apr/{vin}`,\n`/payments/{vin}`, `/taxes/{vin}` and `/tco/{vin}` answer for one VIN per call, market-wide: they are not\nlimited to the caller's sites, and they cannot list or search. An unknown VIN is `404 vin_not_found`.\nTheir query parameters are camelCase (`creditScore`, `tradeIn`, `docFee`, `annualMiles`).\n\n**Estimates.** Every payment, rate, tax, fee and cost figure is an object that carries the `terms` it was\ncomputed from and an `estimate` flag. `estimate: false` marks a figure published by its source (a dealer's\nadvertised price, a window-sticker MSRP, a manufacturer offer); `estimate: true` marks our computation.\nNone of it is an offer of credit.\n\n**Plans.** Each operation names the lowest plan that may call it in `x-md-tier`\n(`free`, `growth`, `scale`, `enterprise`) and the billing units of one call in `x-md-units`.\n`x-md-corpus: true` marks a route that reads across every dealer for one VIN. Routes that can walk a\ndealer or the market (inventory pages, feeds, search) are `enterprise`.\n\n**Limits.** Each request has a 4 second database budget (`504 query_timeout` beyond it), an hourly\nper-key rate limit (`429 rate_limited`, `X-RateLimit-*` headers) and the agency's monthly usage cap\n(`429 usage_cap_exceeded`).\n" }, "servers": [ { "url": "https://api.motorsdynamic.com/api/v2" } ], "security": [ { "apiKey": [] }, { "bearer": [] } ], "tags": [ { "name": "dealers" }, { "name": "inventory" }, { "name": "history" }, { "name": "market" }, { "name": "offers" }, { "name": "specials" }, { "name": "vin" }, { "name": "reference" }, { "name": "finance" } ], "paths": { "/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "This document, as JSON.", "security": [], "tags": [ "dealers" ], "responses": { "200": { "description": "OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/dealers": { "get": { "operationId": "listDealers", "x-md-title": "Dealers", "x-md-tier": "enterprise", "x-md-units": 10, "summary": "Sites (rooftops) the caller is entitled to.", "tags": [ "dealers" ], "parameters": [ { "name": "host", "in": "query", "description": "Exact host, for example `exampledealer.com` (scheme and `www.` are ignored).", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit100" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "One page of sites, ordered by id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealerPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } }, "post": { "operationId": "registerDealer", "x-md-title": "Register a dealer", "x-md-tier": "enterprise", "x-md-units": 10, "summary": "Register a site for an agency.", "description": "Idempotent. A host MotorsDynamic already crawls only gains the agency entitlement. A new host\nbecomes a discovery-tier site (`serving=false`): it is crawled in shadow and nothing is\npublished until it is promoted. Needs scope `v2:write` (keys) or role admin and above (sessions).\nReturns 201 when anything was created, 200 when everything already existed.\n", "tags": [ "dealers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterDealerRequest" } } } }, "responses": { "200": { "description": "Already registered for this agency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterDealerResponse" } } } }, "201": { "description": "Registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterDealerResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/dealers/{domainId}/recrawl": { "post": { "operationId": "recrawlDealer", "x-md-title": "Request a recrawl", "x-md-tier": "enterprise", "x-md-units": 10, "summary": "Ask for a targeted follow-up crawl.", "description": "Moves the site's next scheduled crawl to now. It never starts a second, parallel crawl: while a\ncrawl is running the answer is `in_progress`; during failure backoff `409 backing_off`; within\n15 minutes of a complete crawl `429 recently_crawled`. Sites crawled only by the legacy pipeline\nhave no v2 crawl target (`404 not_scheduled`).\n", "tags": [ "dealers" ], "parameters": [ { "$ref": "#/components/parameters/domainId" }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "inventory", "offers", "oem_inventory", "media", "stickers", "specials" ], "default": "inventory" } } ], "responses": { "202": { "description": "Accepted; see `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecrawlResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/dealers/{domainId}/inventory": { "get": { "operationId": "listInventory", "x-md-title": "Dealer inventory", "x-md-tier": "enterprise", "x-md-units": 10, "summary": "Current listings of one site.", "tags": [ "inventory" ], "parameters": [ { "$ref": "#/components/parameters/domainId" }, { "name": "condition", "in": "query", "schema": { "type": "string", "enum": [ "new", "used", "cpo" ] } }, { "name": "make", "in": "query", "description": "Case-insensitive exact match.", "schema": { "type": "string" } }, { "name": "model", "in": "query", "description": "Case-insensitive exact match.", "schema": { "type": "string" } }, { "name": "year_min", "in": "query", "schema": { "type": "integer" } }, { "name": "year_max", "in": "query", "schema": { "type": "integer" } }, { "name": "price_min", "in": "query", "schema": { "type": "number" } }, { "name": "price_max", "in": "query", "schema": { "type": "number" } }, { "name": "powertrain", "in": "query", "schema": { "type": "string", "enum": [ "gas", "diesel", "hybrid", "phev", "electric", "hydrogen", "unknown" ] } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "last_seen_at", "first_seen_at", "price", "year", "mileage" ], "default": "last_seen_at" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "$ref": "#/components/parameters/limit100" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "One page of listings. Missing values sort last in either order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/dealers/{domainId}/changes": { "get": { "operationId": "listChanges", "x-md-title": "Inventory change feed", "x-md-tier": "enterprise", "x-md-units": 10, "summary": "Change feed of one site.", "description": "Listing events (listed, price and status changes, ...) written by the v2 crawler, in commit-safe\norder (by writing transaction, then event id). Poll with the returned `next_cursor`; it is\nreturned even when the page is empty. An event becomes visible once every transaction older\nthan its own has finished (`meta.watermark`), which guarantees that a cursor never skips an\nevent committed later. Sites still written by the legacy pipeline (`meta.emits_events: false`)\nhave an empty feed until they are promoted.\n", "tags": [ "history" ], "parameters": [ { "$ref": "#/components/parameters/domainId" }, { "name": "since", "in": "query", "description": "Start of the feed (RFC 3339) when no cursor is given. Default 24 hours ago.", "schema": { "type": "string", "format": "date-time" } }, { "name": "types", "in": "query", "description": "Comma-separated event types.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "One page of events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/dealers/{domainId}/new-units": { "get": { "operationId": "listNewUnits", "x-md-tier": "enterprise", "x-md-units": 10, "x-md-title": "New units and in-transit", "summary": "New cars of one store, with in-stock or in-transit status.", "description": "The new cars that belong to one physical store, wherever they are listed. Group sites list the\nwhole group's pooled inventory, so each car is attributed to its store by the per-car rooftop on\nthe listing (rooftop_attribution), not by the site. Status comes from the store's OEM inventory row\nwhen that brand's feed was read in the last 36 hours, else from the dealer site's own per-car flag,\nelse `unknown`. `in_transit` covers cars in production and on the way (`stock_status_detail` says\nwhich). `expected_arrival` is the source's date when it gives one (OEM delivery date, or the start\nof the dealer site's ETA window); `expected_arrival_end` is the end of that window. Dealer sites do not\nalways update a car's ETA, so `arrival_overdue` is true for a car the source still calls in transit\nafter its whole window (or its single date) has passed: treat that date as stale. Sorted by VIN.\n", "tags": [ "inventory" ], "parameters": [ { "$ref": "#/components/parameters/domainId" }, { "name": "stock_status", "in": "query", "schema": { "type": "string", "enum": [ "in_stock", "in_transit", "unknown" ] } }, { "name": "make", "in": "query", "description": "Case-insensitive exact match.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "One page of the store's new cars; meta.counts covers the whole store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewUnitPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/vehicles/{vin}/timeline": { "get": { "operationId": "getVehicleTimeline", "x-md-title": "Vehicle history", "x-md-summary": "Every listing, price change and removal recorded for a VIN, oldest first.", "x-md-description": "Every event recorded for a VIN, oldest first: the first listing, each price change, status changes and removal, with the dealer site it was seen on. `meta.sources` reports the status of each history source. A page with a failing source has `meta.partial: true` and no `next_cursor`: retry it.", "x-md-tier": "free", "x-md-units": 15, "x-md-corpus": true, "summary": "Everything known about one VIN, across the caller's sites and history sources.", "description": "Events from the v2 event store and the history archives, oldest first. `sources` picks the\nprovenances (default `v2,md_legacy`, plus `foureyes` for keys with scope `history:foureyes`).\n`meta.sources` reports each source's status: `ok`, `unavailable` (not configured on this\nserver), `timeout` or `error`; a failing archive never fails the request. A page with a\n`timeout` or `error` source has `meta.partial: true` and no `next_cursor` (continuing would skip\nthat source's events): retry, or leave the failing source out of `sources`.\n", "tags": [ "history" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Za-hj-npr-z0-9]{17}$" } }, { "name": "sources", "in": "query", "description": "Comma-separated subset of v2, md_legacy, foureyes.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 } }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "One page of events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/market/prices": { "get": { "operationId": "getMarketPrices", "x-md-title": "Market prices", "x-md-summary": "The price range of current dealer inventory for a make and model.", "x-md-tier": "growth", "x-md-units": 50, "x-md-corpus": true, "summary": "Price distribution of current inventory for a make and model.", "description": "Market-wide statistics over active dealer-site listings. Results covering fewer than 3 dealers\nare suppressed (`suppressed: too_few_dealers`). Legacy Team Velocity prices, known to be wrong on\nmost such sites, are excluded unless `include_suspect=true`.\n", "tags": [ "market" ], "parameters": [ { "name": "make", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "year", "in": "query", "schema": { "type": "integer" } }, { "name": "year_min", "in": "query", "schema": { "type": "integer" } }, { "name": "year_max", "in": "query", "schema": { "type": "integer" } }, { "name": "trim", "in": "query", "schema": { "type": "string" } }, { "name": "condition", "in": "query", "schema": { "type": "string", "enum": [ "new", "used", "cpo" ] } }, { "name": "include_suspect", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } } ], "responses": { "200": { "description": "Statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketPricesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/offers": { "get": { "operationId": "listOffers", "x-md-title": "OEM incentives", "x-md-summary": "Current OEM incentives with full terms: APR, lease and cash offers by make and model.", "x-md-tier": "growth", "x-md-units": 50, "x-md-corpus": true, "summary": "OEM offers with versioned terms.", "tags": [ "offers" ], "parameters": [ { "name": "make", "in": "query", "schema": { "type": "string" } }, { "name": "model", "in": "query", "schema": { "type": "string" } }, { "name": "year", "in": "query", "schema": { "type": "integer" } }, { "name": "zip", "in": "query", "schema": { "type": "string", "pattern": "^\\d{5}$" } }, { "name": "offer_type", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "all" ], "default": "active" } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "include", "in": "query", "description": "`history` adds each offer's last 50 term changes.", "schema": { "type": "string", "enum": [ "history" ] } }, { "$ref": "#/components/parameters/limit100" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "One page of offers, ordered by id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/targets": { "post": { "operationId": "registerTargets", "x-md-title": "Register specials targets", "x-md-tier": "enterprise", "x-md-units": 10, "summary": "Register sites for a collection kind (dealer-site specials).", "description": "Idempotent, up to 200 sites per call. Each site is matched by exact normalized host; an unknown\nhost becomes a new site. Creates the `(site, kind)` collection target if it does not exist and\nnever changes an existing one. New targets start in shadow (collected and diffed, not\npublished) until the site passes parity and is promoted. Records the agency's entitlement, so the\ncredential can read the site's specials, history and runs. `seed_urls` (known specials pages,\non the site's host) and `group_hosts` (sister-store hosts whose images count as dealer-owned)\nare merged with earlier registrations. Kinds `media`, `site_pages` and `ad_library` are planned\n(`400 kind_not_available`). Needs scope `v2:write`. Returns 201 when anything was created.\n", "tags": [ "specials" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTargetsRequest" } } } }, "responses": { "200": { "description": "Everything already registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTargetsResponse" } } } }, "201": { "description": "Registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTargetsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/targets/{domainId}": { "delete": { "operationId": "deleteTarget", "x-md-title": "Remove a specials target", "x-md-tier": "enterprise", "x-md-units": 10, "summary": "Stop collecting a kind for the caller's agency.", "description": "Revokes the agency's registration. The target itself is removed only when no other agency\nregistered it and it is still a shadow (discovery) target; a published target keeps running\n(`kept_serving`). The agency keeps read access to history already collected.\n", "tags": [ "specials" ], "parameters": [ { "$ref": "#/components/parameters/domainId" }, { "name": "kinds", "in": "query", "schema": { "type": "string", "enum": [ "specials" ], "default": "specials" } }, { "name": "agency_id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "What happened per kind.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTargetResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/targets/{domainId}/refresh": { "post": { "operationId": "refreshTarget", "x-md-title": "Refresh specials", "x-md-tier": "enterprise", "x-md-units": 10, "summary": "Customer-triggered crawl of one collection kind.", "description": "Same rules as `POST /dealers/{domainId}/recrawl`, defaulting to `kind=specials`: moves the next\nrun to now, never starts a parallel run, `409 backing_off` during failure backoff,\n`429 recently_crawled` within 15 minutes of a complete run.\n", "tags": [ "specials" ], "parameters": [ { "$ref": "#/components/parameters/domainId" }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "inventory", "specials" ], "default": "specials" } } ], "responses": { "202": { "description": "Accepted; see `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecrawlResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/specials": { "get": { "operationId": "listSpecials", "x-md-title": "Dealer specials", "x-md-tier": "enterprise", "x-md-units": 10, "summary": "Dealer-site specials with stable ids.", "description": "`id` is stable for the life of an offer on its site (same platform offer id, same creative, or\nsame make/model/year/type/amount): a changed payment keeps the id and is recorded in the\nhistory; an offer that disappears and returns keeps its id. `source=published` (default) is what\nv2 publishes; `source=shadow` is what it would publish for sites still in shadow. For\nincremental sync pass `since` (rows changed or removed since then) with `status=all`.\n", "tags": [ "specials" ], "parameters": [ { "name": "domain_id", "in": "query", "description": "One site; without it, every entitled site.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "removed", "all" ], "default": "active" } }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "published", "shadow" ], "default": "published" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "make", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 } }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "One page of specials, ordered by id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecialPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/specials/history": { "get": { "operationId": "listSpecialsHistory", "x-md-title": "Specials change feed", "x-md-tier": "enterprise", "x-md-units": 10, "summary": "A site's specials change feed.", "description": "Ascending `history_id`. `page.next_cursor` is always set: keep polling with it. Within a site the\norder is commit order (one writer per site at a time), so a cursor never skips a change.\n", "tags": [ "specials" ], "parameters": [ { "name": "domain_id", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "published", "shadow" ], "default": "published" } }, { "name": "types", "in": "query", "description": "Comma list of change types.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2000, "default": 500 } }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "One page of changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecialChangePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/specials/{specialId}/history": { "get": { "operationId": "getSpecialHistory", "x-md-title": "Special history", "x-md-tier": "enterprise", "x-md-units": 10, "summary": "One special's change log.", "tags": [ "specials" ], "parameters": [ { "name": "specialId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "published", "shadow" ], "default": "published" } } ], "responses": { "200": { "description": "Every recorded change, oldest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecialHistoryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/runs": { "get": { "operationId": "listRuns", "x-md-title": "Collection runs", "x-md-tier": "enterprise", "x-md-units": 10, "summary": "Collection run history of a site.", "description": "Newest first. Specials runs carry the never-blank outcome, OCR and LLM counts.", "tags": [ "specials" ], "parameters": [ { "name": "domain_id", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "inventory", "specials" ], "default": "specials" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "One page of runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/vin/{vin}": { "get": { "operationId": "decodeVin", "x-md-title": "VIN decode", "x-md-tier": "free", "x-md-units": 25, "x-md-corpus": true, "summary": "Decode a VIN.", "description": "Year, make, model, trim, body, engine, transmission and drive of the car a VIN names (NHTSA vPIC decode stored with our listings).\n", "tags": [ "vin" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinDecodeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/listings/{vin}": { "get": { "operationId": "getVinListings", "x-md-title": "Listings for a VIN", "x-md-tier": "free", "x-md-units": 15, "x-md-corpus": true, "summary": "Where a VIN is listed, and at what advertised price.", "description": "Every dealer site that lists or listed the car. `listing` is the freshest active one, or null when the car is not on any site today. An advertised price carries what it includes (`price.terms`).\n", "tags": [ "vin" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinListingsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/photos/{vin}": { "get": { "operationId": "getVinPhotos", "x-md-title": "Photos", "x-md-tier": "free", "x-md-units": 9, "x-md-corpus": true, "summary": "Photos of a VIN.", "description": "Photo URLs from the largest gallery among the car's listings.\n", "tags": [ "vin" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinPhotosResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/build/{vin}": { "get": { "operationId": "getVinBuild", "x-md-title": "Window sticker", "x-md-tier": "growth", "x-md-units": 800, "x-md-corpus": true, "summary": "Window sticker (Monroney label) of a VIN.", "description": "Base price, priced options, destination charge and equipment as printed on the manufacturer's window sticker of this exact car. `404 build_not_available` when no sticker is on file.\n", "tags": [ "vin" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinBuildResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/specs/{vin}": { "get": { "operationId": "getVinSpecs", "x-md-title": "Specifications", "x-md-tier": "free", "x-md-units": 15, "x-md-corpus": true, "summary": "Specifications of a VIN.", "description": "The decode merged with what the dealer listing states: body, engine, transmission, drive, efficiency, colors, features and option codes.\n", "tags": [ "vin" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinSpecsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/history/{vin}": { "get": { "operationId": "getVinHistory", "x-md-title": "Listing and price history", "x-md-tier": "free", "x-md-units": 15, "x-md-corpus": true, "summary": "Listing and price timeline of a VIN.", "description": "Every site that listed the car, with days on lot, and each change of its advertised price.\n", "tags": [ "history" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinHistoryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/recalls/{vin}": { "get": { "operationId": "getVinRecalls", "x-md-title": "Recalls", "x-md-tier": "free", "x-md-units": 50, "x-md-corpus": true, "summary": "Recall campaigns for the model year, make and model of a VIN.", "description": "NHTSA recall campaigns issued for the car's model year, make and model (`scope: year_make_model`). This is not a per-VIN result: it does not say whether this car is included in a campaign or has been repaired.\nUntil the year, make and model has been fetched from NHTSA the answer is `503 reference_data_pending`. When NHTSA answered nothing for the model under any name we tried, in any dataset, the answer is `404 reference_no_match`: an empty list is returned only for a model NHTSA is known to carry. Neither is billed.\n", "tags": [ "reference" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinRecallsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ReferencePending" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/complaints/{vin}": { "get": { "operationId": "getVinComplaints", "x-md-title": "Owner complaints", "x-md-tier": "free", "x-md-units": 50, "x-md-corpus": true, "summary": "Owner complaints for the model year, make and model of a VIN.", "description": "NHTSA owner complaints, summarized: totals, crashes, fires, injuries, deaths, counts by component and the ten most recent.\n", "tags": [ "reference" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinComplaintsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ReferencePending" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/safety/{vin}": { "get": { "operationId": "getVinSafety", "x-md-title": "Safety ratings", "x-md-tier": "free", "x-md-units": 50, "x-md-corpus": true, "summary": "NHTSA safety ratings for a VIN.", "description": "NCAP star ratings of the car's model year, make and model. `rating` is the variant matching the car's drive type; `variants` lists every rated variant.\n", "tags": [ "reference" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinSafetyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ReferencePending" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/fuel/{vin}": { "get": { "operationId": "getVinFuel", "x-md-title": "Fuel economy", "x-md-tier": "free", "x-md-units": 15, "x-md-corpus": true, "summary": "Fuel economy, range and emissions of a VIN.", "description": "The EPA (fueleconomy.gov) configuration matching the decode: MPG or MPGe, range, annual fuel cost, CO2. `match` says how exactly the configuration was singled out.\n", "tags": [ "reference" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinFuelResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/apr/{vin}": { "get": { "operationId": "getVinApr", "x-md-title": "Interest rates", "x-md-tier": "growth", "x-md-units": 50, "x-md-corpus": true, "summary": "Market APR for a VIN by credit tier.", "description": "Estimated market APR for each credit tier (published tier averages moved by the change in the Federal Reserve G.19 benchmark since), average credit-union and bank rates, and the manufacturer's financing offers for the model, nearest the ZIP first. With `creditScore`, `apr` is the estimate for that score.\n", "tags": [ "finance" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" }, { "name": "zip", "in": "query", "description": "5-digit ZIP code of a US state or DC.", "schema": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" } }, { "name": "creditScore", "in": "query", "description": "Credit score; picks the credit tier.", "schema": { "type": "integer", "minimum": 300, "maximum": 850 } }, { "name": "condition", "in": "query", "description": "Which rate table to read. Default: the listing's condition.", "schema": { "type": "string", "enum": [ "new", "used" ] } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinAprResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ReferencePending" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/payments/{vin}": { "get": { "operationId": "getVinPayments", "x-md-title": "Payments", "x-md-tier": "growth", "x-md-units": 50, "x-md-corpus": true, "summary": "Loan and lease payment estimates for a VIN.", "description": "A loan payment on the advertised (or given) price, with taxes and fees for the ZIP when one is given, and a lease payment when the manufacturer publishes a money factor and residual for the model. Every figure carries its terms; none is an offer of credit.\n", "tags": [ "finance" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" }, { "name": "price", "in": "query", "description": "Price to compute on. Default: the dealer's advertised price.", "schema": { "type": "number", "minimum": 1 } }, { "name": "zip", "in": "query", "description": "5-digit ZIP code of a US state or DC.", "schema": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" } }, { "name": "term", "in": "query", "description": "Loan term in months.", "schema": { "type": "integer", "minimum": 12, "maximum": 96, "default": 60 } }, { "name": "down", "in": "query", "description": "Cash down payment.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "tradeIn", "in": "query", "description": "Trade-in value.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "rebate", "in": "query", "description": "Manufacturer rebate applied to the price.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "docFee", "in": "query", "description": "Dealer documentation fee. Default: the fee crawled with the car's listing.", "schema": { "type": "number", "minimum": 0 } }, { "name": "creditScore", "in": "query", "description": "Credit score; picks the credit tier.", "schema": { "type": "integer", "minimum": 300, "maximum": 850 } }, { "name": "apr", "in": "query", "description": "APR in percent. Default: the market estimate for the credit tier.", "schema": { "type": "number", "minimum": 0, "maximum": 100 } }, { "name": "condition", "in": "query", "description": "Which rate table to read. Default: the listing's condition.", "schema": { "type": "string", "enum": [ "new", "used" ] } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinPaymentsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ReferencePending" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/taxes/{vin}": { "get": { "operationId": "getVinTaxes", "x-md-title": "Taxes and fees", "x-md-tier": "growth", "x-md-units": 50, "x-md-corpus": true, "summary": "Sales tax and fees on a VIN for a ZIP.", "description": "State sales tax, an average local tax, title and registration fees for the ZIP's state, plus the dealer's documentation fee as crawled with the listing.\n", "tags": [ "finance" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" }, { "name": "zip", "in": "query", "required": true, "description": "5-digit ZIP code of a US state or DC.", "schema": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" } }, { "name": "price", "in": "query", "description": "Price to compute on. Default: the dealer's advertised price.", "schema": { "type": "number", "minimum": 1 } }, { "name": "tradeIn", "in": "query", "description": "Trade-in value.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "rebate", "in": "query", "description": "Manufacturer rebate applied to the price.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "docFee", "in": "query", "description": "Dealer documentation fee. Default: the fee crawled with the car's listing.", "schema": { "type": "number", "minimum": 0 } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinTaxesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ReferencePending" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/tco/{vin}": { "get": { "operationId": "getVinTco", "x-md-title": "Total cost of ownership", "x-md-tier": "growth", "x-md-units": 500, "x-md-corpus": true, "summary": "Five-year cost of ownership of a VIN.", "description": "Depreciation from market asking prices of the model by model year, EPA fuel cost, and insurance and maintenance assumptions that are labelled and can be replaced. Taxes and fees are added with `zip`, loan interest with `apr`.\n", "tags": [ "finance" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" }, { "name": "zip", "in": "query", "description": "5-digit ZIP code of a US state or DC.", "schema": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" } }, { "name": "price", "in": "query", "description": "Price to compute on. Default: the dealer's advertised price.", "schema": { "type": "number", "minimum": 1 } }, { "name": "annualMiles", "in": "query", "description": "Miles driven a year.", "schema": { "type": "integer", "minimum": 1000, "maximum": 100000, "default": 15000 } }, { "name": "insuranceAnnual", "in": "query", "description": "Annual insurance premium. Default: a published national average.", "schema": { "type": "number", "minimum": 0 } }, { "name": "maintenancePerMile", "in": "query", "description": "Maintenance, repair and tire cost per mile. Default: a published national average.", "schema": { "type": "number", "minimum": 0 } }, { "name": "apr", "in": "query", "description": "APR in percent. Default: the market estimate for the credit tier.", "schema": { "type": "number", "minimum": 0, "maximum": 100 } }, { "name": "term", "in": "query", "description": "Loan term in months.", "schema": { "type": "integer", "minimum": 12, "maximum": 96, "default": 60 } }, { "name": "down", "in": "query", "description": "Cash down payment.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "tradeIn", "in": "query", "description": "Trade-in value.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "rebate", "in": "query", "description": "Manufacturer rebate applied to the price.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "docFee", "in": "query", "description": "Dealer documentation fee. Default: the fee crawled with the car's listing.", "schema": { "type": "number", "minimum": 0 } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinTcoResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ReferencePending" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/openrecalls/{vin}": { "get": { "operationId": "getVinOpenRecalls", "x-md-title": "Open recalls", "x-md-tier": "scale", "x-md-units": 500, "x-md-corpus": true, "summary": "Recall status of this exact car, as its manufacturer reports it.", "description": "Asks the manufacturer's own VIN recall lookup which safety recalls are open on this car, and which it reports as repaired. Unlike `/recalls/{vin}` this is about the VIN (`scope: vin`, `vin_specific: true`).\nThe manufacturer is asked when the car has not been checked in the last 7 days; the answer is stored and served until then (`freshness.cached`). Covered makes: Honda, Acura, Chevrolet, GMC, Buick, Cadillac; any other make is `404 open_recalls_not_supported`.\n\"None open\" is only ever a manufacturer answer inside that window: when the manufacturer cannot be reached the answer is `502 source_unavailable`, and a VIN it does not know is `404 vin_not_recognized_by_maker`. Neither is billed. Always show `provenance.manufacturer` and `freshness.checked_at` with the result.\n", "tags": [ "reference" ], "parameters": [ { "$ref": "#/components/parameters/vinPath" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinOpenRecallsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "$ref": "#/components/responses/SourceUnavailable" }, "503": { "$ref": "#/components/responses/ReferencePending" }, "504": { "$ref": "#/components/responses/Timeout" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "parameters": { "domainId": { "name": "domainId", "in": "path", "required": true, "description": "Site id (`id` from GET /dealers).", "schema": { "type": "integer", "minimum": 1 } }, "cursor": { "name": "cursor", "in": "query", "description": "`page.next_cursor` from the previous page, unchanged.", "schema": { "type": "string" } }, "limit100": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, "vinPath": { "name": "vin", "in": "path", "required": true, "description": "17-character VIN (case-insensitive).", "schema": { "type": "string", "minLength": 17, "maxLength": 17 } } }, "responses": { "BadRequest": { "description": "Invalid parameter or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Not entitled to this site, source or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "The request conflicts with the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Rate limit, usage cap, or recrawl too soon.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "SourceUnavailable": { "description": "The source this answer comes from did not answer or could not be read (`source_unavailable`). Not billed; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ReferencePending": { "description": "The reference data this answer needs is not loaded yet (`reference_data_pending`, `reference_data_unavailable`). Not billed; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Timeout": { "description": "The query exceeded its 4 second budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Machine-readable code, for example not_entitled, invalid_cursor, query_timeout." }, "message": { "type": "string" }, "parameter": { "type": "string" }, "retry_at": { "type": [ "string", "null" ] }, "retry_after_seconds": { "type": "integer" } } }, "Page": { "type": "object", "required": [ "limit", "has_more", "next_cursor" ], "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "Timestamp": { "type": [ "string", "null" ], "description": "RFC 3339 UTC with microseconds." }, "Freshness": { "type": "object", "required": [ "last_seen_at", "observed_at" ], "properties": { "last_seen_at": { "$ref": "#/components/schemas/Timestamp" }, "observed_at": { "$ref": "#/components/schemas/Timestamp" }, "age_seconds": { "type": [ "integer", "null" ] } } }, "Dealer": { "type": "object", "required": [ "id", "url", "host", "tier", "crawl", "freshness", "provenance" ], "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "host": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "tier": { "type": "string", "enum": [ "serving_legacy", "serving_v2", "discovery" ] }, "crawl": { "type": [ "object", "null" ], "properties": { "owner": { "type": "string", "enum": [ "legacy", "v2" ] }, "serving": { "type": "boolean" }, "next_crawl_at": { "$ref": "#/components/schemas/Timestamp" }, "last_complete_at": { "$ref": "#/components/schemas/Timestamp" } } }, "freshness": { "type": "object", "required": [ "last_seen_at" ], "properties": { "last_seen_at": { "$ref": "#/components/schemas/Timestamp" } } }, "provenance": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "domains", "v2_domains" ] } } } } }, "DealerPage": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dealer" } }, "page": { "$ref": "#/components/schemas/Page" }, "meta": { "type": "object" } } }, "RegisterDealerRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Website, for example https://www.exampledealer.com" }, "name": { "type": "string" }, "agency_id": { "type": "integer", "description": "Required only when the credential can act for more than one agency." }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "inventory", "offers", "oem_inventory", "media", "stickers", "specials" ] }, "default": [ "inventory" ] } } }, "RegisterDealerResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Dealer" }, { "type": "object", "required": [ "agency_id", "created" ], "properties": { "agency_id": { "type": "integer" }, "created": { "type": "object", "required": [ "site", "targets", "entitlement" ], "properties": { "site": { "type": "boolean" }, "targets": { "type": "array", "items": { "type": "string" } }, "entitlement": { "type": "boolean" } } } } } ] } } }, "RecrawlResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "domain_id", "kind", "status" ], "properties": { "domain_id": { "type": "integer" }, "kind": { "type": "string" }, "status": { "type": "string", "enum": [ "scheduled", "already_due", "in_progress" ] }, "run_id": { "type": "integer" }, "next_crawl_at": { "$ref": "#/components/schemas/Timestamp" } } } } }, "Listing": { "type": "object", "required": [ "id", "vin", "domain_id", "url", "status", "price_flags", "freshness", "provenance" ], "properties": { "id": { "type": "integer", "description": "Stable listing id (same as /v1 vehicles.id)." }, "vin": { "type": "string" }, "domain_id": { "type": "integer" }, "url": { "type": "string" }, "stock_number": { "type": [ "string", "null" ] }, "condition": { "type": [ "string", "null" ], "enum": [ "new", "used", "cpo", null ] }, "condition_raw": { "type": [ "string", "null" ] }, "is_cpo": { "type": "boolean" }, "year": { "type": [ "integer", "null" ] }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "trim": { "type": [ "string", "null" ] }, "body_type": { "type": [ "string", "null" ] }, "exterior_color": { "type": [ "string", "null" ] }, "interior_color": { "type": [ "string", "null" ] }, "drivetrain": { "type": [ "string", "null" ] }, "transmission": { "type": [ "string", "null" ] }, "engine": { "type": [ "string", "null" ] }, "fuel_type": { "type": [ "string", "null" ] }, "powertrain": { "type": [ "string", "null" ] }, "mileage": { "type": [ "integer", "null" ] }, "price": { "type": [ "number", "null" ], "description": "Advertised price." }, "msrp": { "type": [ "number", "null" ] }, "sale_price": { "type": [ "number", "null" ] }, "price_basis": { "type": [ "string", "null" ], "description": "How the v2 adapter derived the price (v2 sites only)." }, "price_flags": { "type": "array", "description": "`suspect_teamvelocity`: legacy Team Velocity price, known to be wrong on most such sites.", "items": { "type": "string" } }, "image_count": { "type": "integer" }, "primary_image": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active" ] }, "first_seen_at": { "$ref": "#/components/schemas/Timestamp" }, "freshness": { "$ref": "#/components/schemas/Freshness" }, "provenance": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "v2", "md_legacy" ] }, "adapter_version": { "type": [ "string", "null" ] }, "run_id": { "type": [ "integer", "null" ] }, "episode": { "type": [ "integer", "null" ] } } } } }, "NewUnit": { "type": "object", "required": [ "vin", "stock_status", "store_domain_id", "listed_on", "last_seen_at" ], "properties": { "vin": { "type": "string" }, "year": { "type": [ "integer", "null" ] }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "trim": { "type": [ "string", "null" ] }, "stock_number": { "type": [ "string", "null" ] }, "stock_status": { "type": "string", "enum": [ "in_stock", "in_transit", "unknown" ] }, "stock_status_detail": { "type": [ "string", "null" ], "enum": [ "in_stock", "in_transit", "in_production", null ] }, "status_source": { "type": [ "string", "null" ], "description": "'oem:' (for example oem:kia.com) or 'dealer_site'; null when unknown." }, "expected_arrival": { "type": [ "string", "null" ], "format": "date" }, "expected_arrival_end": { "type": [ "string", "null" ], "format": "date", "description": "End of the dealer site's ETA window; null when the source gives a single date or none." }, "arrival_overdue": { "type": "boolean", "description": "True when the car is still in transit after expected_arrival_end (or expected_arrival) has passed." }, "store_domain_id": { "type": "integer" }, "store_name": { "type": [ "string", "null" ] }, "listed_on": { "type": "array", "description": "Every MD site id whose dealer-site listing shows this VIN.", "items": { "type": "integer" } }, "url": { "type": [ "string", "null" ] }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "NewUnitPage": { "type": "object", "required": [ "data", "page", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NewUnit" } }, "page": { "$ref": "#/components/schemas/Page" }, "meta": { "type": "object" } } }, "InventoryPage": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Listing" } }, "page": { "$ref": "#/components/schemas/Page" }, "meta": { "type": "object" } } }, "Event": { "type": "object", "required": [ "event_id", "domain_id", "vin", "event_type", "observed_at", "freshness", "provenance" ], "properties": { "event_id": { "type": "string", "format": "uuid" }, "domain_id": { "type": [ "integer", "null" ] }, "vin": { "type": [ "string", "null" ] }, "source_key": { "type": [ "string", "null" ] }, "event_type": { "type": "string", "enum": [ "listed", "price_changed", "price_basis_changed", "mileage_changed", "photos_changed", "status_changed", "correction" ] }, "observed_at": { "type": "string" }, "prev": { "description": "State before the event (object or null)." }, "next": { "description": "State after the event (object or null)." }, "entity_version": { "type": [ "integer", "null" ] }, "episode": { "type": [ "integer", "null" ] }, "freshness": { "type": "object", "required": [ "observed_at" ], "properties": { "observed_at": { "type": "string" } } }, "provenance": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "v2", "md_legacy", "foureyes" ] }, "adapter_version": { "type": [ "string", "null" ] }, "run_id": { "type": [ "integer", "null" ] }, "quality": { "type": [ "string", "null" ], "description": "Comma list of archive caveats, for example mass_removal_hour." } } } } }, "TimelinePage": { "type": "object", "required": [ "data", "page", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "page": { "$ref": "#/components/schemas/Page" }, "meta": { "type": "object", "required": [ "vin", "sources", "partial" ], "properties": { "vin": { "type": "string" }, "partial": { "type": "boolean" }, "sources": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "ok", "unavailable", "timeout", "error" ] } } } } } }, "ChangePage": { "type": "object", "required": [ "data", "page", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "page": { "$ref": "#/components/schemas/Page" }, "meta": { "type": "object", "required": [ "domain_id", "watermark", "writer", "emits_events" ], "properties": { "domain_id": { "type": "integer" }, "watermark": { "type": "string", "description": "Oldest running transaction id; events of older transactions are complete." }, "since": { "type": [ "string", "null" ] }, "writer": { "type": "string", "enum": [ "legacy", "v2" ] }, "emits_events": { "type": "boolean" } } } } }, "MarketPricesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "query", "listings", "dealers", "suppressed", "price", "freshness", "provenance" ], "properties": { "query": { "type": "object" }, "listings": { "type": "integer" }, "dealers": { "type": "integer" }, "suppressed": { "type": [ "string", "null" ], "enum": [ "too_few_dealers", null ] }, "price": { "type": [ "object", "null" ], "properties": { "min": { "type": [ "number", "null" ] }, "p10": { "type": [ "number", "null" ] }, "p25": { "type": [ "number", "null" ] }, "median": { "type": [ "number", "null" ] }, "p75": { "type": [ "number", "null" ] }, "p90": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "mean": { "type": [ "number", "null" ] } } }, "msrp_median": { "type": [ "number", "null" ] }, "mileage_median": { "type": [ "number", "null" ] }, "excluded_suspect_listings": { "type": "integer" }, "freshness": { "type": "object", "required": [ "oldest_last_seen_at", "newest_last_seen_at", "as_of" ], "properties": { "oldest_last_seen_at": { "$ref": "#/components/schemas/Timestamp" }, "newest_last_seen_at": { "$ref": "#/components/schemas/Timestamp" }, "as_of": { "type": "string" } } }, "provenance": { "type": "object", "required": [ "v2", "md_legacy" ], "properties": { "v2": { "type": "integer", "description": "Listings written by the v2 crawler." }, "md_legacy": { "type": "integer", "description": "Listings written by the legacy pipeline." } } } } }, "meta": { "type": "object" } } }, "Offer": { "type": "object", "required": [ "id", "make", "terms", "valid", "status", "version", "freshness", "provenance" ], "properties": { "id": { "type": "integer" }, "offer_key": { "type": [ "string", "null" ] }, "make": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "model_year": { "type": [ "integer", "null" ] }, "trim": { "description": "Trim list or object as published by the OEM." }, "body_style": { "type": [ "string", "null" ] }, "model_code": { "type": [ "string", "null" ] }, "offer_type": { "type": [ "string", "null" ] }, "condition": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "disclaimer": { "type": [ "string", "null" ] }, "value_display": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "geography": { "type": "object", "properties": { "postal_code": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] } } }, "terms": { "type": "object", "properties": { "cash_amount": { "type": [ "number", "null" ] }, "apr": { "type": [ "number", "null" ] }, "apr_term_months": { "type": [ "integer", "null" ] }, "lease_payment": { "type": [ "number", "null" ] }, "lease_term": { "type": [ "integer", "null" ] }, "lease_due": { "type": [ "number", "null" ] }, "msrp": { "type": [ "number", "null" ] }, "selling_price": { "type": [ "number", "null" ] } } }, "valid": { "type": "object", "properties": { "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" } } }, "status": { "type": "string", "enum": [ "active", "removed" ] }, "removed_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "type": "object", "required": [ "number" ], "properties": { "number": { "type": "integer", "description": "1 + recorded term changes." }, "last_changed_at": { "$ref": "#/components/schemas/Timestamp" } } }, "first_seen_at": { "$ref": "#/components/schemas/Timestamp" }, "freshness": { "$ref": "#/components/schemas/Freshness" }, "provenance": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "oem_offers" ] }, "source_id": { "type": [ "integer", "null" ] }, "program_id": { "type": [ "integer", "null" ] }, "vendor": { "type": [ "integer", "null" ] } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "change_type": { "type": "string" }, "field": { "type": [ "string", "null" ] }, "old_value": { "type": [ "string", "null" ] }, "new_value": { "type": [ "string", "null" ] }, "changed_at": { "$ref": "#/components/schemas/Timestamp" } } } } } }, "OfferPage": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "page": { "$ref": "#/components/schemas/Page" }, "meta": { "type": "object" } } }, "RegisterTargetsRequest": { "type": "object", "required": [ "domains" ], "properties": { "agency_id": { "type": "integer", "description": "Required only when the credential can act for more than one agency." }, "domains": { "type": "array", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "specials" ] }, "default": [ "specials" ] }, "seed_urls": { "type": "array", "items": { "type": "string" } }, "group_hosts": { "type": "array", "items": { "type": "string" } }, "cms_hint": { "type": "string" } } } } } }, "RegisterTargetsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "domain_id", "host", "created", "targets" ], "properties": { "domain_id": { "type": "integer" }, "host": { "type": "string" }, "created": { "type": "object", "required": [ "site", "targets", "entitlement" ], "properties": { "site": { "type": "boolean" }, "targets": { "type": "array", "items": { "type": "string" } }, "entitlement": { "type": "boolean" } } }, "targets": { "type": "array", "items": { "type": "object", "required": [ "kind", "mode" ], "properties": { "kind": { "type": "string" }, "mode": { "type": "string", "enum": [ "shadow", "publish" ] }, "next_crawl_at": { "$ref": "#/components/schemas/Timestamp" }, "last_complete_at": { "$ref": "#/components/schemas/Timestamp" } } } } } } }, "meta": { "type": "object" } } }, "DeleteTargetResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "domain_id", "agency_id", "kinds" ], "properties": { "domain_id": { "type": "integer" }, "agency_id": { "type": "integer" }, "kinds": { "type": "array", "items": { "type": "object", "required": [ "kind", "status" ], "properties": { "kind": { "type": "string" }, "status": { "type": "string", "enum": [ "not_registered", "kept_for_other_agencies", "target_removed", "kept_serving" ] } } } } } } } }, "Special": { "type": "object", "required": [ "id", "domain_id", "source", "status", "offer_key", "first_seen_at", "last_seen_at", "freshness", "provenance" ], "properties": { "id": { "type": "integer", "description": "Stable special id." }, "domain_id": { "type": "integer" }, "source": { "type": "string", "enum": [ "published", "shadow" ] }, "status": { "type": "string", "enum": [ "active", "removed" ] }, "offer_key": { "type": "string" }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "model_year": { "type": [ "integer", "null" ] }, "trim": { "type": [ "string", "null" ] }, "vin": { "type": [ "string", "null" ] }, "stock_number": { "type": [ "string", "null" ] }, "offer_type": { "type": [ "string", "null" ] }, "offer_amount": { "type": [ "string", "null" ] }, "monthly_payment": { "type": [ "number", "null" ] }, "term": { "type": [ "integer", "null" ] }, "due_at_signing": { "type": [ "number", "null" ] }, "msrp": { "type": [ "number", "null" ] }, "selling_price": { "type": [ "number", "null" ] }, "offer_details": { "type": [ "string", "null" ] }, "disclaimer": { "type": [ "string", "null" ] }, "raw_ocr_text": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "description": "YYYY-MM-DD" }, "offers": { "type": [ "array", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "image_hash": { "type": [ "string", "null" ] }, "source_type": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "source_page_type": { "type": [ "string", "null" ] }, "strategy": { "type": [ "string", "null" ] }, "first_seen_at": { "$ref": "#/components/schemas/Timestamp" }, "last_seen_at": { "$ref": "#/components/schemas/Timestamp" }, "removed_at": { "$ref": "#/components/schemas/Timestamp" }, "freshness": { "type": "object", "required": [ "last_seen_at", "last_complete_run_at", "stale" ], "properties": { "last_seen_at": { "$ref": "#/components/schemas/Timestamp" }, "last_complete_run_at": { "$ref": "#/components/schemas/Timestamp" }, "stale": { "type": "boolean" } } }, "provenance": { "type": "object", "required": [ "source", "mode" ], "properties": { "source": { "type": "string", "enum": [ "v2_specials" ] }, "mode": { "type": "string", "enum": [ "shadow", "publish" ] }, "strategy": { "type": [ "string", "null" ], "description": "How the offer was found: tv_api, scene7_params, structured_slides, banner_ocr, offer_text (a card read as HTML text), ai_located, image_discovered." }, "extractor": { "type": [ "string", "null" ], "description": "The extractor that read the offer: offer-text:overfuel, offer-text:dealercom-promos, banner-ocr, scene7-params, structured-slides, dealervenom-card, tv-offers, reading: (a stored reading of the creative). Additive (2026-09-29)." }, "run_id": { "type": [ "integer", "null" ] }, "first_run_id": { "type": [ "integer", "null" ] } } } } }, "SpecialPage": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Special" } }, "page": { "$ref": "#/components/schemas/Page" }, "meta": { "type": "object" } } }, "SpecialChange": { "type": "object", "required": [ "history_id", "special_id", "domain_id", "change_type", "changed_cols", "observed_at", "provenance" ], "properties": { "history_id": { "type": "integer" }, "special_id": { "type": "integer" }, "domain_id": { "type": "integer" }, "change_type": { "type": "string", "enum": [ "listed", "changed", "relisted", "removed", "adopted" ] }, "changed_cols": { "type": "array", "items": { "type": "string" } }, "prev": { "type": [ "object", "null" ] }, "next": { "type": [ "object", "null" ] }, "observed_at": { "$ref": "#/components/schemas/Timestamp" }, "provenance": { "type": "object", "required": [ "source", "mode" ], "properties": { "source": { "type": "string", "enum": [ "v2_specials" ] }, "mode": { "type": "string", "enum": [ "shadow", "publish" ] }, "run_id": { "type": [ "integer", "null" ] } } } } }, "SpecialChangePage": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SpecialChange" } }, "page": { "$ref": "#/components/schemas/Page" }, "meta": { "type": "object" } } }, "SpecialHistoryResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SpecialChange" } }, "meta": { "type": "object" } } }, "Run": { "type": "object", "required": [ "run_id", "domain_id", "kind", "state", "mode", "started_at", "finished_at", "counts" ], "properties": { "run_id": { "type": "integer" }, "domain_id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "inventory", "specials" ] }, "state": { "type": "string", "enum": [ "claimed", "running", "complete", "incomplete", "failed", "expired" ] }, "mode": { "type": "string", "enum": [ "shadow", "publish" ] }, "started_at": { "$ref": "#/components/schemas/Timestamp" }, "finished_at": { "$ref": "#/components/schemas/Timestamp" }, "adapter_version": { "type": [ "string", "null" ] }, "fetch_tier": { "type": [ "string", "null" ] }, "pages_fetched": { "type": [ "integer", "null" ] }, "requests": { "type": [ "integer", "null" ] }, "counts": { "type": "object", "properties": { "added": { "type": "integer" }, "changed": { "type": "integer" }, "unchanged": { "type": "integer" }, "removed": { "type": "integer" } } }, "error": { "type": [ "object", "null" ], "properties": { "class": { "type": "string" }, "message": { "type": [ "string", "null" ] } } }, "specials": { "type": [ "object", "null" ], "properties": { "outcome": { "type": "string", "enum": [ "RECIPE_HIT", "DISCOVERY_HIT", "SWEEP_INCOMPLETE", "RECIPE_MISS", "CONFIRMED_NONE" ] }, "reason": { "type": [ "string", "null" ] }, "cms": { "type": [ "string", "null" ] }, "observations": { "type": "integer" }, "listed": { "type": "integer" }, "changed": { "type": "integer" }, "relisted": { "type": "integer" }, "unchanged": { "type": "integer" }, "removed": { "type": "integer" }, "renders": { "type": "integer" }, "ocr_read": { "type": "integer" }, "ocr_skipped": { "type": "object" }, "llm_calls": { "type": "integer" }, "llm_capped": { "type": "boolean" }, "strategies": { "type": "object" } } } } }, "RunPage": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, "page": { "$ref": "#/components/schemas/Page" }, "meta": { "type": "object" } } }, "VinVehicle": { "type": "object", "required": [ "year", "make", "model", "trim" ], "properties": { "year": { "type": [ "integer", "null" ] }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "trim": { "type": [ "string", "null" ] } } }, "AdvertisedPrice": { "description": "A dealer's advertised price with what it includes. Never an estimate.", "type": "object", "required": [ "amount", "currency", "estimate", "terms" ], "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] }, "estimate": { "type": "boolean", "enum": [ false ] }, "terms": { "type": "object", "required": [ "basis", "msrp", "includes_dealer_fees", "dealer_fees", "fee_disclaimer", "excludes", "observed_at" ], "properties": { "basis": { "type": "string", "enum": [ "dealer_advertised" ] }, "msrp": { "type": [ "number", "null" ] }, "includes_dealer_fees": { "type": [ "boolean", "null" ] }, "dealer_fees": { "type": [ "number", "null" ] }, "fee_disclaimer": { "type": [ "string", "null" ] }, "excludes": { "type": "string" }, "observed_at": { "type": [ "string", "null" ] } } } } }, "VinListing": { "type": "object", "required": [ "domain_id", "status", "dealer", "vdp_url", "stock_number", "condition", "is_cpo", "stock_status", "price", "mileage", "exterior_color", "interior_color", "photo_count", "primary_image", "carfax_available", "first_seen_at", "removed_at", "days_on_lot", "freshness", "provenance" ], "properties": { "domain_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "removed" ] }, "dealer": { "type": "object", "required": [ "name", "website", "city", "state", "zip", "location" ], "properties": { "name": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "location": { "type": [ "object", "null" ], "required": [ "lat", "lon" ], "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } } } } }, "vdp_url": { "type": [ "string", "null" ] }, "stock_number": { "type": [ "string", "null" ] }, "condition": { "type": [ "string", "null" ], "enum": [ "new", "used", "cpo", null ] }, "is_cpo": { "type": "boolean" }, "stock_status": { "type": [ "string", "null" ] }, "price": { "oneOf": [ { "$ref": "#/components/schemas/AdvertisedPrice" }, { "type": "null" } ] }, "mileage": { "type": [ "integer", "null" ] }, "exterior_color": { "type": [ "string", "null" ] }, "interior_color": { "type": [ "string", "null" ] }, "photo_count": { "type": "integer" }, "primary_image": { "type": [ "string", "null" ] }, "carfax_available": { "type": [ "boolean", "null" ] }, "first_seen_at": { "type": [ "string", "null" ] }, "removed_at": { "type": [ "string", "null" ] }, "days_on_lot": { "type": [ "integer", "null" ] }, "freshness": { "$ref": "#/components/schemas/Freshness" }, "provenance": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "vehicles" ] } } } } }, "VinDecodeResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "type": "object" }, "data": { "type": "object", "required": [ "vin", "check_digit_valid", "wmi", "year", "make", "model", "trim", "decoded", "freshness", "provenance" ], "properties": { "vin": { "type": "string" }, "check_digit_valid": { "type": "boolean" }, "wmi": { "type": "string" }, "year": { "type": [ "integer", "null" ] }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "trim": { "type": [ "string", "null" ] }, "decoded": { "type": "object", "required": [ "year", "make", "model", "trim", "body_style", "vehicle_type", "doors", "engine", "engine_cylinders", "engine_displacement_l", "fuel_type", "transmission", "drive_type" ], "properties": { "year": { "type": [ "integer", "null" ] }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "trim": { "type": [ "string", "null" ] }, "body_style": { "type": [ "string", "null" ] }, "vehicle_type": { "type": [ "string", "null" ] }, "doors": { "type": [ "integer", "null" ] }, "engine": { "type": [ "string", "null" ] }, "engine_cylinders": { "type": [ "integer", "null" ] }, "engine_displacement_l": { "type": [ "number", "null" ] }, "fuel_type": { "type": [ "string", "null" ] }, "transmission": { "type": [ "string", "null" ] }, "drive_type": { "type": [ "string", "null" ] } } }, "freshness": { "type": "object", "required": [ "decoded_at" ], "properties": { "decoded_at": { "type": [ "string", "null" ] } } }, "provenance": { "type": "object", "required": [ "source", "lookup" ], "properties": { "source": { "type": "string", "enum": [ "nhtsa_vpic", "listing" ] }, "lookup": { "type": "string", "enum": [ "vehicles", "decode", "vin_cache" ] } } } } } } }, "VinListingsResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "type": "object", "required": [ "active_listings", "total_listings" ], "properties": { "active_listings": { "type": "integer" }, "total_listings": { "type": "integer" } } }, "data": { "type": "object", "required": [ "vin", "online", "vehicle", "listing", "listings" ], "properties": { "vin": { "type": "string" }, "online": { "type": "boolean" }, "vehicle": { "allOf": [ { "$ref": "#/components/schemas/VinVehicle" }, { "type": "object", "required": [ "body_type", "engine", "transmission", "drivetrain", "fuel_type" ], "properties": { "body_type": { "type": [ "string", "null" ] }, "engine": { "type": [ "string", "null" ] }, "transmission": { "type": [ "string", "null" ] }, "drivetrain": { "type": [ "string", "null" ] }, "fuel_type": { "type": [ "string", "null" ] } } } ] }, "listing": { "oneOf": [ { "$ref": "#/components/schemas/VinListing" }, { "type": "null" } ] }, "listings": { "type": "array", "items": { "$ref": "#/components/schemas/VinListing" } } } } } }, "VinPhotosResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "type": "object" }, "data": { "type": "object", "required": [ "vin", "vehicle", "count", "photos", "video_url", "source", "freshness" ], "properties": { "vin": { "type": "string" }, "vehicle": { "$ref": "#/components/schemas/VinVehicle" }, "count": { "type": "integer" }, "photos": { "type": "array", "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] }, "source": { "type": [ "object", "null" ], "required": [ "domain_id", "vdp_url", "status" ], "properties": { "domain_id": { "type": "integer" }, "vdp_url": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "removed" ] } } }, "freshness": { "type": "object", "required": [ "last_seen_at" ], "properties": { "last_seen_at": { "type": [ "string", "null" ] } } } } } } }, "VinBuildResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "type": "object" }, "data": { "type": "object", "required": [ "vin", "vehicle", "verified", "pricing", "options", "features", "equipment", "freshness", "provenance" ], "properties": { "vin": { "type": "string" }, "vehicle": { "$ref": "#/components/schemas/VinVehicle" }, "verified": { "type": "boolean", "description": "Base, options and destination matched the total printed on the label." }, "pricing": { "type": "object", "required": [ "base_price", "options_total", "destination_charge", "total_msrp", "currency", "estimate", "terms" ], "properties": { "base_price": { "type": [ "number", "null" ], "description": "null when the base price could not be read from the label." }, "options_total": { "type": [ "number", "null" ] }, "destination_charge": { "type": [ "number", "null" ] }, "total_msrp": { "type": [ "number", "null" ], "description": "Base plus options plus destination; null when the base price is unknown." }, "currency": { "type": "string", "enum": [ "USD" ] }, "estimate": { "type": "boolean", "enum": [ false ] }, "terms": { "type": "object", "required": [ "basis", "description" ], "properties": { "basis": { "type": "string", "enum": [ "manufacturer_window_sticker" ] }, "description": { "type": "string" } } } } }, "options": { "type": "array", "items": { "type": "object", "required": [ "name", "price" ], "properties": { "name": { "type": "string" }, "price": { "type": [ "number", "null" ] } } } }, "features": { "type": "array", "items": { "type": "string" } }, "equipment": { "type": [ "object", "null" ], "description": "Equipment by section, as printed on the label." }, "freshness": { "type": "object", "required": [ "parsed_at" ], "properties": { "parsed_at": { "type": [ "string", "null" ] } } }, "provenance": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "monroney_label" ] } } } } } } }, "VinSpecsResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "type": "object" }, "data": { "type": "object", "required": [ "vin", "year", "make", "model", "trim", "body", "engine", "transmission", "drive_type", "efficiency", "colors", "wheels", "features", "option_codes", "provenance" ], "properties": { "vin": { "type": "string" }, "year": { "type": [ "integer", "null" ] }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "trim": { "type": [ "string", "null" ] }, "body": { "type": "object", "required": [ "style", "vehicle_type", "doors", "seating_capacity" ], "properties": { "style": { "type": [ "string", "null" ] }, "vehicle_type": { "type": [ "string", "null" ] }, "doors": { "type": [ "integer", "null" ] }, "seating_capacity": { "type": [ "integer", "null" ] } } }, "engine": { "type": "object", "required": [ "description", "cylinders", "displacement_l", "fuel_type", "powertrain" ], "properties": { "description": { "type": [ "string", "null" ] }, "cylinders": { "type": [ "integer", "null" ] }, "displacement_l": { "type": [ "number", "null" ] }, "fuel_type": { "type": [ "string", "null" ] }, "powertrain": { "type": [ "string", "null" ] } } }, "transmission": { "type": [ "string", "null" ] }, "drive_type": { "type": [ "string", "null" ] }, "efficiency": { "type": "object", "required": [ "mpg_city", "mpg_highway", "range_miles", "battery_kwh" ], "properties": { "mpg_city": { "type": [ "number", "null" ] }, "mpg_highway": { "type": [ "number", "null" ] }, "range_miles": { "type": [ "number", "null" ] }, "battery_kwh": { "type": [ "number", "null" ] } } }, "colors": { "type": "object", "required": [ "exterior", "interior" ], "properties": { "exterior": { "type": [ "string", "null" ] }, "interior": { "type": [ "string", "null" ] } } }, "wheels": { "type": [ "string", "null" ] }, "features": { "type": "array", "items": { "type": "string" } }, "option_codes": { "type": [ "string", "null" ] }, "provenance": { "type": "object" } } } } }, "VinHistoryResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "type": "object", "required": [ "truncated" ], "properties": { "truncated": { "type": "boolean" } } }, "data": { "type": "object", "required": [ "vin", "vehicle", "summary", "listings", "prices", "price_terms" ], "properties": { "vin": { "type": "string" }, "vehicle": { "$ref": "#/components/schemas/VinVehicle" }, "summary": { "type": "object", "required": [ "first_seen_at", "days_since_first_seen", "price_changes", "first_price", "latest_price", "change" ], "properties": { "first_seen_at": { "type": [ "string", "null" ] }, "days_since_first_seen": { "type": [ "integer", "null" ] }, "price_changes": { "type": "integer" }, "first_price": { "type": [ "number", "null" ] }, "latest_price": { "type": [ "number", "null" ] }, "change": { "type": [ "number", "null" ] } } }, "listings": { "type": "array", "items": { "type": "object", "required": [ "domain_id", "dealer_name", "status", "first_seen_at", "last_seen_at", "removed_at", "days_on_lot", "time_to_sale_days", "current_price" ], "properties": { "domain_id": { "type": "integer" }, "dealer_name": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "removed" ] }, "first_seen_at": { "type": [ "string", "null" ] }, "last_seen_at": { "type": [ "string", "null" ] }, "removed_at": { "type": [ "string", "null" ] }, "days_on_lot": { "type": [ "integer", "null" ] }, "time_to_sale_days": { "type": [ "integer", "null" ] }, "current_price": { "type": [ "number", "null" ] } } } }, "prices": { "type": "array", "items": { "type": "object", "required": [ "observed_at", "domain_id", "price", "msrp" ], "properties": { "observed_at": { "type": "string" }, "domain_id": { "type": [ "integer", "null" ] }, "price": { "type": "number" }, "msrp": { "type": [ "number", "null" ] } } } }, "price_terms": { "type": "object", "required": [ "basis", "estimate", "currency", "excludes" ], "properties": { "basis": { "type": "string", "enum": [ "dealer_advertised" ] }, "estimate": { "type": "boolean", "enum": [ false ] }, "currency": { "type": "string" }, "excludes": { "type": "string" } } } } } } }, "ReferenceMeta": { "type": "object", "required": [ "reference_status" ], "properties": { "reference_status": { "type": "string", "enum": [ "loaded", "no_decode" ], "description": "loaded = fetched from the source, so an empty result is real; no_decode = the VIN has no usable year, make and model. A model not fetched yet is 503 reference_data_pending." } } }, "VinRecallsResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "$ref": "#/components/schemas/ReferenceMeta" }, "data": { "type": "object", "required": [ "vin", "vehicle", "scope", "vin_specific", "notice", "count", "recalls", "freshness", "provenance" ], "properties": { "vin": { "type": "string" }, "vehicle": { "$ref": "#/components/schemas/VinVehicle" }, "scope": { "type": "string", "enum": [ "year_make_model" ] }, "vin_specific": { "type": "boolean", "enum": [ false ] }, "notice": { "type": "string" }, "count": { "type": "integer" }, "recalls": { "type": "array", "items": { "type": "object", "required": [ "campaign_number", "manufacturer", "component", "summary", "consequence", "remedy", "notes", "report_received_date", "park_it", "park_outside", "over_the_air_update", "source_url" ], "properties": { "campaign_number": { "type": "string" }, "manufacturer": { "type": [ "string", "null" ] }, "component": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "consequence": { "type": [ "string", "null" ] }, "remedy": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "report_received_date": { "type": [ "string", "null" ] }, "park_it": { "type": "boolean" }, "park_outside": { "type": "boolean" }, "over_the_air_update": { "type": [ "boolean", "null" ], "description": "null when the source does not say (NHTSA's bulk recall file has no such field)." }, "source_url": { "type": "string" } } } }, "freshness": { "type": "object", "required": [ "fetched_at" ], "properties": { "fetched_at": { "type": [ "string", "null" ] } } }, "provenance": { "type": "object", "required": [ "source", "source_url", "nhtsa_models" ], "properties": { "source": { "type": "string", "enum": [ "nhtsa_recalls" ] }, "source_url": { "type": "string" }, "nhtsa_models": { "type": "array", "items": { "type": "string" }, "description": "The NHTSA model names this answer came from (NHTSA's names differ from the decode's: Silverado is SILVERADO 1500)." } } } } } } }, "VinComplaintsResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "$ref": "#/components/schemas/ReferenceMeta" }, "data": { "type": "object", "required": [ "vin", "vehicle", "scope", "vin_specific", "total", "crashes", "fires", "injuries", "deaths", "latest_filed", "by_component", "recent", "freshness", "provenance" ], "properties": { "vin": { "type": "string" }, "vehicle": { "$ref": "#/components/schemas/VinVehicle" }, "scope": { "type": "string", "enum": [ "year_make_model" ] }, "vin_specific": { "type": "boolean", "enum": [ false ] }, "total": { "type": "integer" }, "crashes": { "type": "integer" }, "fires": { "type": "integer" }, "injuries": { "type": "integer" }, "deaths": { "type": "integer" }, "latest_filed": { "type": [ "string", "null" ] }, "by_component": { "type": "array", "items": { "type": "object", "required": [ "component", "count" ], "properties": { "component": { "type": "string" }, "count": { "type": "integer" } } } }, "recent": { "type": "array", "items": { "type": "object", "required": [ "odi_number", "date_filed", "date_of_incident", "components", "crash", "fire", "injuries", "deaths", "summary" ], "properties": { "odi_number": { "type": [ "integer", "null" ] }, "date_filed": { "type": [ "string", "null" ] }, "date_of_incident": { "type": [ "string", "null" ] }, "components": { "type": "array", "items": { "type": "string" } }, "crash": { "type": "boolean" }, "fire": { "type": "boolean" }, "injuries": { "type": "integer" }, "deaths": { "type": "integer" }, "summary": { "type": [ "string", "null" ] } } } }, "freshness": { "type": "object", "required": [ "fetched_at" ], "properties": { "fetched_at": { "type": [ "string", "null" ] } } }, "provenance": { "type": "object", "required": [ "source", "source_url", "nhtsa_models" ], "properties": { "source": { "type": "string", "enum": [ "nhtsa_complaints" ] }, "source_url": { "type": "string" }, "nhtsa_models": { "type": "array", "items": { "type": "string" }, "description": "The NHTSA model names this answer came from (NHTSA's names differ from the decode's: Silverado is SILVERADO 1500)." } } } } } } }, "SafetyRating": { "type": "object", "required": [ "nhtsa_vehicle_id", "description", "overall", "frontal_crash", "side_crash", "rollover", "features", "counts", "picture_url", "source_url" ], "properties": { "nhtsa_vehicle_id": { "type": "integer" }, "description": { "type": [ "string", "null" ] }, "overall": { "type": [ "integer", "null" ], "description": "Stars, 1 to 5; null = not rated." }, "frontal_crash": { "type": "object", "required": [ "overall", "driver", "passenger" ], "properties": { "overall": { "type": [ "integer", "null" ] }, "driver": { "type": [ "integer", "null" ] }, "passenger": { "type": [ "integer", "null" ] } } }, "side_crash": { "type": "object", "required": [ "overall", "driver", "passenger", "pole" ], "properties": { "overall": { "type": [ "integer", "null" ] }, "driver": { "type": [ "integer", "null" ] }, "passenger": { "type": [ "integer", "null" ] }, "pole": { "type": [ "integer", "null" ] } } }, "rollover": { "type": "object", "required": [ "rating", "probability" ], "properties": { "rating": { "type": [ "integer", "null" ] }, "probability": { "type": [ "number", "null" ] } } }, "features": { "type": "object", "required": [ "electronic_stability_control", "forward_collision_warning", "lane_departure_warning" ], "properties": { "electronic_stability_control": { "type": [ "string", "null" ] }, "forward_collision_warning": { "type": [ "string", "null" ] }, "lane_departure_warning": { "type": [ "string", "null" ] } } }, "counts": { "type": "object", "required": [ "complaints", "recalls", "investigations" ], "properties": { "complaints": { "type": [ "integer", "null" ] }, "recalls": { "type": [ "integer", "null" ] }, "investigations": { "type": [ "integer", "null" ] } } }, "picture_url": { "type": [ "string", "null" ] }, "source_url": { "type": "string" } } }, "VinSafetyResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "$ref": "#/components/schemas/ReferenceMeta" }, "data": { "type": "object", "required": [ "vin", "vehicle", "scope", "rated", "rating", "variants", "freshness", "provenance" ], "properties": { "vin": { "type": "string" }, "vehicle": { "$ref": "#/components/schemas/VinVehicle" }, "scope": { "type": "string", "enum": [ "year_make_model" ] }, "rated": { "type": "boolean" }, "rating": { "oneOf": [ { "$ref": "#/components/schemas/SafetyRating" }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/SafetyRating" } }, "freshness": { "type": "object", "required": [ "fetched_at" ], "properties": { "fetched_at": { "type": [ "string", "null" ] } } }, "provenance": { "type": "object", "required": [ "source", "source_url", "nhtsa_models" ], "properties": { "source": { "type": "string", "enum": [ "nhtsa_ncap" ] }, "source_url": { "type": "string" }, "nhtsa_models": { "type": "array", "items": { "type": "string" }, "description": "The NHTSA model names this answer came from (NHTSA's names differ from the decode's: Silverado is SILVERADO 1500)." } } } } } } }, "VinFuelResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "type": "object" }, "data": { "type": "object", "required": [ "vin", "vehicle", "available", "epa", "mpg", "alternative", "range_miles", "electric_range_miles", "charge_hours_240v", "annual_fuel_cost", "five_year_savings_vs_average", "emissions", "match", "freshness", "provenance" ], "properties": { "vin": { "type": "string" }, "vehicle": { "$ref": "#/components/schemas/VinVehicle" }, "available": { "type": "boolean", "description": "false when EPA does not list the model." }, "epa": { "type": [ "object", "null" ], "required": [ "epa_id", "model", "vehicle_class", "transmission", "drive", "cylinders", "displacement_l", "fuel_type", "electrification" ], "properties": { "epa_id": { "type": "integer" }, "model": { "type": "string" }, "vehicle_class": { "type": [ "string", "null" ] }, "transmission": { "type": [ "string", "null" ] }, "drive": { "type": [ "string", "null" ] }, "cylinders": { "type": [ "integer", "null" ] }, "displacement_l": { "type": [ "number", "null" ] }, "fuel_type": { "type": [ "string", "null" ] }, "electrification": { "type": [ "string", "null" ] } } }, "mpg": { "type": [ "object", "null" ], "required": [ "city", "highway", "combined", "unit" ], "properties": { "city": { "type": [ "integer", "null" ] }, "highway": { "type": [ "integer", "null" ] }, "combined": { "type": [ "integer", "null" ] }, "unit": { "type": "string", "enum": [ "mpg", "mpge" ] } } }, "alternative": { "type": [ "object", "null" ], "required": [ "fuel_type", "city", "highway", "combined", "unit" ], "properties": { "fuel_type": { "type": [ "string", "null" ] }, "city": { "type": [ "integer", "null" ] }, "highway": { "type": [ "integer", "null" ] }, "combined": { "type": [ "integer", "null" ] }, "unit": { "type": "string", "enum": [ "mpg", "mpge" ] } } }, "range_miles": { "type": [ "integer", "null" ] }, "electric_range_miles": { "type": [ "integer", "null" ] }, "charge_hours_240v": { "type": [ "number", "null" ] }, "annual_fuel_cost": { "type": [ "object", "null" ], "required": [ "amount", "currency", "estimate", "terms" ], "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "estimate": { "type": "boolean", "enum": [ true ] }, "terms": { "type": "object", "required": [ "basis", "annual_miles", "description" ], "properties": { "basis": { "type": "string", "enum": [ "epa_estimate" ] }, "annual_miles": { "type": "integer" }, "description": { "type": "string" } } } } }, "five_year_savings_vs_average": { "type": [ "integer", "null" ] }, "emissions": { "type": [ "object", "null" ], "required": [ "co2_grams_per_mile", "ghg_score", "fuel_economy_score" ], "properties": { "co2_grams_per_mile": { "type": [ "number", "null" ] }, "ghg_score": { "type": [ "integer", "null" ] }, "fuel_economy_score": { "type": [ "integer", "null" ] } } }, "match": { "type": [ "object", "null" ], "required": [ "quality", "configurations", "matched_on", "mpg_combined_range" ], "properties": { "quality": { "type": "string", "enum": [ "exact", "narrowed", "model" ] }, "configurations": { "type": "integer" }, "matched_on": { "type": "array", "items": { "type": "string", "enum": [ "fuel", "drive", "cylinders", "displacement", "trim" ] } }, "mpg_combined_range": { "type": [ "object", "null" ], "required": [ "min", "max" ], "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } } } } }, "freshness": { "type": "object", "required": [ "loaded_at", "source_modified_on" ], "properties": { "loaded_at": { "type": [ "string", "null" ] }, "source_modified_on": { "type": [ "string", "null" ] } } }, "provenance": { "type": "object", "required": [ "source", "source_url" ], "properties": { "source": { "type": "string", "enum": [ "epa_fueleconomy" ] }, "source_url": { "type": "string" } } } } } } }, "AprEstimate": { "description": "Estimated market APR for one credit tier, with the published figures it was computed from.", "type": "object", "required": [ "tier", "score_low", "score_high", "apr", "estimate", "terms" ], "properties": { "tier": { "type": "string", "enum": [ "super_prime", "prime", "near_prime", "subprime", "deep_subprime" ] }, "score_low": { "type": "integer" }, "score_high": { "type": "integer" }, "apr": { "type": "number", "description": "Percent." }, "estimate": { "type": "boolean", "enum": [ true ] }, "terms": { "type": "object", "required": [ "product", "method", "tier_average", "benchmark" ], "properties": { "product": { "type": "string", "enum": [ "new", "used" ] }, "method": { "type": "string", "enum": [ "tier_average", "tier_average_plus_benchmark_change" ] }, "tier_average": { "type": "object", "required": [ "apr", "period_end", "source", "source_url" ], "properties": { "apr": { "type": "number" }, "period_end": { "type": "string" }, "source": { "type": "string" }, "source_url": { "type": "string" } } }, "benchmark": { "type": [ "object", "null" ], "required": [ "series", "description", "apr_at_period", "period_observed_on", "apr_latest", "latest_observed_on", "change", "source_url" ], "properties": { "series": { "type": "string" }, "description": { "type": "string" }, "apr_at_period": { "type": "number" }, "period_observed_on": { "type": "string" }, "apr_latest": { "type": "number" }, "latest_observed_on": { "type": "string" }, "change": { "type": "number" }, "source_url": { "type": "string" } } } } } } }, "VinAprResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "type": "object", "required": [ "default_term_months" ], "properties": { "default_term_months": { "type": "integer" } } }, "data": { "type": "object", "required": [ "vin", "vehicle", "zip", "state", "product", "credit_score", "apr", "by_term", "tiers", "lender_averages", "manufacturer_offers", "disclosure" ], "properties": { "vin": { "type": "string" }, "vehicle": { "$ref": "#/components/schemas/VinVehicle" }, "zip": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "product": { "type": "string", "enum": [ "new", "used" ] }, "credit_score": { "type": [ "integer", "null" ] }, "apr": { "oneOf": [ { "$ref": "#/components/schemas/AprEstimate" }, { "type": "null" } ] }, "by_term": { "type": [ "object", "null" ], "description": "The estimate for the credit score at each loan term the Fed publishes (months to percent).", "additionalProperties": { "type": "number" } }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/AprEstimate" } }, "lender_averages": { "type": "array", "items": { "type": "object", "required": [ "lender_type", "term_months", "apr", "observed_on", "source", "source_url" ], "properties": { "lender_type": { "type": "string", "enum": [ "credit_union", "bank" ] }, "term_months": { "type": "integer" }, "apr": { "type": "number" }, "observed_on": { "type": "string" }, "source": { "type": "string" }, "source_url": { "type": "string" } } } }, "manufacturer_offers": { "type": "array", "items": { "type": "object", "required": [ "offer_id", "title", "apr", "term_months", "trims", "geography", "postal_code", "end_date", "disclaimer", "estimate", "terms" ], "properties": { "offer_id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "trims": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Trims the offer names; null = the whole model." }, "apr": { "type": "number" }, "term_months": { "type": [ "integer", "null" ] }, "geography": { "type": "string", "enum": [ "same_zip", "same_area", "same_state", "other_region", "not_compared" ] }, "postal_code": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] }, "disclaimer": { "type": [ "string", "null" ] }, "estimate": { "type": "boolean", "enum": [ false ] }, "terms": { "type": "object" } } } }, "disclosure": { "type": "string" } } } } }, "TaxesAndFees": { "description": "Sales tax and fees with the rates and sources they were computed from. Always an estimate.", "type": "object", "required": [ "taxable_amount", "taxes", "fees", "total_taxes_and_fees", "terms", "estimate" ], "properties": { "taxable_amount": { "type": "number" }, "taxes": { "type": "object", "required": [ "state_sales_tax", "local_sales_tax", "combined_sales_tax", "capped" ], "properties": { "state_sales_tax": { "type": "number" }, "local_sales_tax": { "type": "number" }, "combined_sales_tax": { "type": "number" }, "capped": { "type": "boolean" } } }, "fees": { "type": "object", "required": [ "title_fee", "registration_fee", "doc_fee", "combined_fees" ], "properties": { "title_fee": { "type": "number" }, "registration_fee": { "type": "number" }, "doc_fee": { "type": "number" }, "combined_fees": { "type": "number" } } }, "total_taxes_and_fees": { "type": "number" }, "estimate": { "type": "boolean", "enum": [ true ] }, "terms": { "type": "object", "required": [ "state", "tax_name", "state_rate", "local_rate", "combined_rate", "local_rate_basis", "local_taxable_cap", "trade_in", "trade_in_credited", "trade_in_credit_applied", "rebate", "rebate_taxed", "tax_cap_amount", "registration_basis", "registration_notes", "price", "price_source", "doc_fee_source", "doc_fee_label", "doc_fee_cap", "effective_date", "source_url", "fees_source_url", "notes" ], "properties": { "state": { "type": "string" }, "tax_name": { "type": [ "string", "null" ] }, "state_rate": { "type": "number" }, "local_rate": { "type": "number" }, "combined_rate": { "type": "number" }, "local_rate_basis": { "type": "string", "enum": [ "state_average" ] }, "local_taxable_cap": { "type": [ "number", "null" ] }, "trade_in": { "type": "number" }, "trade_in_credited": { "type": "boolean" }, "trade_in_credit_applied": { "type": "number" }, "rebate": { "type": "number" }, "rebate_taxed": { "type": "boolean" }, "tax_cap_amount": { "type": [ "number", "null" ] }, "registration_basis": { "type": [ "string", "null" ] }, "registration_notes": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "price_source": { "type": "string", "enum": [ "query", "dealer_advertised" ] }, "doc_fee_source": { "type": "string", "enum": [ "query", "dealer_listing", "not_published" ] }, "doc_fee_label": { "type": [ "string", "null" ] }, "doc_fee_cap": { "type": [ "number", "null" ] }, "effective_date": { "type": "string" }, "source_url": { "type": "string" }, "fees_source_url": { "type": "string" }, "notes": { "type": [ "string", "null" ] } } } } }, "VinTaxesResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "type": "object" }, "data": { "allOf": [ { "$ref": "#/components/schemas/TaxesAndFees" }, { "type": "object", "required": [ "vin", "vehicle", "zip", "state", "disclosure" ], "properties": { "vin": { "type": "string" }, "vehicle": { "$ref": "#/components/schemas/VinVehicle" }, "zip": { "type": "string" }, "state": { "type": "string" }, "disclosure": { "type": "string" } } } ] } } }, "LoanEstimate": { "type": "object", "required": [ "monthly_payment", "amount_financed", "total_interest", "total_of_payments", "terms", "estimate" ], "properties": { "monthly_payment": { "type": "number" }, "amount_financed": { "type": "number" }, "total_interest": { "type": "number" }, "total_of_payments": { "type": "number" }, "estimate": { "type": "boolean", "enum": [ true ] }, "terms": { "type": "object", "required": [ "apr", "term_months", "down_payment", "trade_in", "rebate", "taxes_and_fees_financed", "price", "price_source", "apr_source", "credit_tier", "credit_score", "apr_basis", "taxes_and_fees_included" ], "properties": { "apr": { "type": "number" }, "term_months": { "type": "integer" }, "down_payment": { "type": "number" }, "trade_in": { "type": "number" }, "rebate": { "type": "number" }, "taxes_and_fees_financed": { "type": "number" }, "price": { "type": "number" }, "price_source": { "type": "string", "enum": [ "query", "dealer_advertised" ] }, "apr_source": { "type": "string", "enum": [ "query", "market_estimate", "market_estimate_default_tier" ] }, "credit_tier": { "type": [ "string", "null" ] }, "credit_score": { "type": [ "integer", "null" ] }, "apr_basis": { "type": [ "object", "null" ] }, "taxes_and_fees_included": { "type": "boolean" } } } } }, "LeaseEstimate": { "type": "object", "required": [ "monthly_payment", "monthly_payment_before_tax", "monthly_depreciation", "monthly_rent_charge", "monthly_tax", "upfront_tax", "due_at_signing", "adjusted_cap_cost", "residual_value", "total_of_payments", "terms", "estimate" ], "properties": { "monthly_payment": { "type": "number" }, "monthly_payment_before_tax": { "type": "number" }, "monthly_depreciation": { "type": "number" }, "monthly_rent_charge": { "type": "number" }, "monthly_tax": { "type": "number" }, "upfront_tax": { "type": "number" }, "due_at_signing": { "type": "number" }, "adjusted_cap_cost": { "type": "number" }, "residual_value": { "type": "number" }, "total_of_payments": { "type": "number" }, "estimate": { "type": "boolean", "enum": [ true ] }, "terms": { "type": "object", "required": [ "term_months", "money_factor", "equivalent_apr", "residual_pct", "msrp", "cap_cost", "cap_cost_reduction", "rebate", "acquisition_fee", "acquisition_fee_capitalized", "tax_rate", "tax_basis", "tax_state", "offer", "description" ], "properties": { "term_months": { "type": "integer" }, "money_factor": { "type": "number" }, "equivalent_apr": { "type": "number" }, "residual_pct": { "type": "number" }, "msrp": { "type": "number" }, "cap_cost": { "type": "number" }, "cap_cost_reduction": { "type": "number" }, "rebate": { "type": "number" }, "acquisition_fee": { "type": "number" }, "acquisition_fee_capitalized": { "type": "boolean" }, "tax_rate": { "type": "number" }, "tax_basis": { "type": "string", "enum": [ "monthly_payment", "upfront_total_payments", "upfront_full_price", "none" ] }, "tax_state": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "offer": { "type": "object", "required": [ "offer_id", "title", "trims", "geography", "postal_code", "end_date", "advertised_payment", "advertised_due_at_signing", "disclaimer", "observed_at" ], "properties": { "offer_id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "trims": { "type": [ "array", "null" ], "items": { "type": "string" } }, "geography": { "type": "string", "enum": [ "same_zip", "same_area", "same_state", "other_region", "not_compared" ] }, "postal_code": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] }, "advertised_payment": { "type": [ "number", "null" ] }, "advertised_due_at_signing": { "type": [ "number", "null" ] }, "disclaimer": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ] } } } } } } }, "VinPaymentsResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "type": "object" }, "data": { "type": "object", "required": [ "vin", "vehicle", "zip", "state", "price", "loan", "taxes_and_fees", "lease", "lease_unavailable_reason", "disclosure" ], "properties": { "vin": { "type": "string" }, "vehicle": { "$ref": "#/components/schemas/VinVehicle" }, "zip": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "price": { "type": "object", "required": [ "amount", "currency", "source" ], "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "source": { "type": "string", "enum": [ "query", "dealer_advertised" ] } } }, "loan": { "$ref": "#/components/schemas/LoanEstimate" }, "taxes_and_fees": { "oneOf": [ { "$ref": "#/components/schemas/TaxesAndFees" }, { "type": "null" } ] }, "lease": { "oneOf": [ { "$ref": "#/components/schemas/LeaseEstimate" }, { "type": "null" } ] }, "lease_unavailable_reason": { "type": [ "string", "null" ], "enum": [ "no_manufacturer_lease_offer", "no_money_factor_published", "msrp_unknown", "offer_terms_do_not_fit", null ] }, "disclosure": { "type": "string" } } } } }, "TcoInput": { "description": "One input of the ownership-cost estimate, with where it came from.", "type": "object", "required": [ "amount", "source", "basis", "source_url", "estimate" ], "properties": { "amount": { "type": [ "number", "null" ] }, "source": { "type": "string", "enum": [ "default_assumption", "query" ] }, "basis": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "estimate": { "type": "boolean", "enum": [ true ] } } }, "VinTcoResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "type": "object" }, "data": { "type": "object", "required": [ "vin", "vehicle", "zip", "state", "years", "total", "estimate", "terms", "disclosure" ], "properties": { "vin": { "type": "string" }, "vehicle": { "$ref": "#/components/schemas/VinVehicle" }, "zip": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "estimate": { "type": "boolean", "enum": [ true ] }, "years": { "type": "array", "items": { "type": "object", "required": [ "year", "depreciation", "depreciation_basis", "value_end_of_year", "fuel", "insurance", "maintenance_and_repairs", "taxes_and_fees", "finance_interest", "total" ], "properties": { "year": { "type": "integer" }, "depreciation": { "type": "number" }, "depreciation_basis": { "type": "string", "enum": [ "market", "default_curve" ] }, "value_end_of_year": { "type": "number" }, "fuel": { "type": [ "number", "null" ] }, "insurance": { "type": "number" }, "maintenance_and_repairs": { "type": "number" }, "taxes_and_fees": { "type": "number" }, "finance_interest": { "type": "number" }, "total": { "type": "number" } } } }, "total": { "type": "object", "required": [ "depreciation", "fuel", "insurance", "maintenance_and_repairs", "taxes_and_fees", "finance_interest", "total", "cost_per_mile" ], "properties": { "depreciation": { "type": "number" }, "fuel": { "type": [ "number", "null" ] }, "insurance": { "type": "number" }, "maintenance_and_repairs": { "type": "number" }, "taxes_and_fees": { "type": "number" }, "finance_interest": { "type": "number" }, "total": { "type": "number" }, "cost_per_mile": { "type": "number" } } }, "terms": { "type": "object", "required": [ "ownership_years", "price", "price_source", "annual_miles", "depreciation", "fuel", "insurance_annual", "maintenance_per_mile", "taxes_and_fees", "financing" ], "properties": { "ownership_years": { "type": "integer" }, "price": { "type": "number" }, "price_source": { "type": "string", "enum": [ "query", "dealer_advertised" ] }, "annual_miles": { "$ref": "#/components/schemas/TcoInput" }, "insurance_annual": { "$ref": "#/components/schemas/TcoInput" }, "maintenance_per_mile": { "$ref": "#/components/schemas/TcoInput" }, "fuel": { "type": "object", "required": [ "amount", "source", "basis", "match_quality", "epa_id", "source_url", "estimate" ], "properties": { "amount": { "type": [ "number", "null" ] }, "source": { "type": "string", "enum": [ "epa_fueleconomy", "not_available" ] }, "basis": { "type": "string" }, "match_quality": { "type": [ "string", "null" ], "enum": [ "exact", "narrowed", "model", null ] }, "epa_id": { "type": [ "integer", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "estimate": { "type": "boolean", "enum": [ true ] } } }, "depreciation": { "type": "object", "required": [ "basis", "market", "estimate" ], "properties": { "basis": { "type": "string" }, "estimate": { "type": "boolean", "enum": [ true ] }, "market": { "type": "array", "items": { "type": "object", "required": [ "age", "model_year", "median_price", "listings", "dealers" ], "properties": { "age": { "type": "integer" }, "model_year": { "type": "integer" }, "median_price": { "type": "number" }, "listings": { "type": "integer" }, "dealers": { "type": "integer" } } } } } }, "taxes_and_fees": { "type": "object" }, "financing": { "type": "object" } } }, "disclosure": { "type": "string" } } } } }, "VinRecallCampaign": { "description": "One campaign the manufacturer lists for this VIN.", "type": "object", "required": [ "campaign_id", "nhtsa_campaign", "status", "title", "description", "safety_risk", "remedy", "recall_date", "repair_date", "maker_status", "nhtsa_url" ], "properties": { "campaign_id": { "type": "string", "description": "The manufacturer's own campaign number." }, "nhtsa_campaign": { "type": [ "string", "null" ], "description": "NHTSA campaign number, for example 21V050000." }, "status": { "type": "string", "enum": [ "open", "remedied", "unknown" ], "description": "unknown = the manufacturer gave a status we could not read; never treat it as repaired." }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "safety_risk": { "type": [ "string", "null" ] }, "remedy": { "type": [ "string", "null" ] }, "recall_date": { "type": [ "string", "null" ] }, "repair_date": { "type": [ "string", "null" ] }, "maker_status": { "type": [ "string", "null" ], "description": "The manufacturer's own wording of the status." }, "nhtsa_url": { "type": [ "string", "null" ] } } }, "VinOpenRecallsResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "meta": { "type": "object" }, "data": { "type": "object", "required": [ "vin", "vehicle", "scope", "vin_specific", "open_count", "remedied_count", "recalls", "other_campaigns", "notice", "freshness", "provenance" ], "properties": { "vin": { "type": "string" }, "vehicle": { "$ref": "#/components/schemas/VinVehicle" }, "scope": { "type": "string", "enum": [ "vin" ] }, "vin_specific": { "type": "boolean", "enum": [ true ] }, "open_count": { "type": "integer", "description": "Safety recalls not reported as repaired on this car (unknown statuses included)." }, "remedied_count": { "type": "integer", "description": "Safety recalls the manufacturer reports as repaired. Some manufacturers list only open ones." }, "recalls": { "type": "array", "description": "Safety recalls filed with NHTSA, open ones first.", "items": { "$ref": "#/components/schemas/VinRecallCampaign" } }, "other_campaigns": { "type": "array", "description": "Special coverage, emission and customer programs. Not safety recalls.", "items": { "$ref": "#/components/schemas/VinRecallCampaign" } }, "notice": { "type": "string" }, "freshness": { "type": "object", "required": [ "checked_at", "cached", "source_updated", "cache_days" ], "properties": { "checked_at": { "type": "string", "description": "When the manufacturer was asked." }, "cached": { "type": "boolean" }, "source_updated": { "type": [ "string", "null" ], "description": "The manufacturer's own data date, when it gives one." }, "cache_days": { "type": "integer" } } }, "provenance": { "type": "object", "required": [ "source", "manufacturer", "source_url" ], "properties": { "source": { "type": "string", "enum": [ "manufacturer_recall_lookup" ] }, "manufacturer": { "type": "string" }, "source_url": { "type": "string" } } } } } } } } } }