Automotive inventory search for AI assistants: vehicles, dealers, deals, and market data.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Bearer API key sent as 'Bearer <key>'. Request a key from [email protected]; self-serve issuance is planned (roadmap A8).
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Open safety recalls for a listing. Pass vertical when the request names one. Cars use NHTSA (year, make, and model; a campaign may not apply to every VIN). Off-road uses CPSC. Call this with the off-road listing id; the tool reads GET /v2/listings/{listingId}/recalls and does not use the cars-only /v1 path for that id. Every response names the source and states one outcome in words: "confirmed for this VIN", "possible for this year, make, and model", "no matching published recall", or "coverage unavailable". An empty list is not "no recalls." Say the outcome. Do not invent a recall or a VIN range. Required step in vehicle_dossier and safety_first playbooks.
17-character Vehicle Identification Number
Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals.
Canonical listing id (`dealerId-or-slug:VIN`). Required for an off-road unit when the VIN is listed at more than one rooftop. Same path key as GET /v2/listings/{listingId}/recalls.
Tool list last changed Oct 25, 2026.
Open safety recalls for a listing. Pass vertical when the request names one. Cars use NHTSA (year, make, and model; a campaign may not apply to every VIN). Off-road uses CPSC. Call this with the off-road listing id; the tool reads GET /v2/listings/{listingId}/recalls and does not use the cars-only /v1 path for that id. Every response names the source and states one outcome in words: "confirmed for this VIN", "possible for this year, make, and model", "no matching published recall", or "coverage unavailable". An empty list is not "no recalls." Say the outcome. Do not invent a recall or a VIN range. Required step in vehicle_dossier and safety_first playbooks.
| Argument | Type | Description |
|---|---|---|
| vin | any | 17-character Vehicle Identification Number |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| listingId | string | Canonical listing id (`dealerId-or-slug:VIN`). Required for an off-road unit when the VIN is listed at more than one rooftop. Same path key as GET /v2/listings/{listingId}/recalls. |
{
"type": "object",
"properties": {
"vin": {
"description": "17-character Vehicle Identification Number"
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"listingId": {
"type": "string",
"maxLength": 300,
"minLength": 1,
"description": "Canonical listing id (`dealerId-or-slug:VIN`). Required for an off-road unit when the VIN is listed at more than one rooftop. Same path key as GET /v2/listings/{listingId}/recalls."
}
},
"additionalProperties": false
}Compare pricing across market segments. Provide cohortKeys or make (optionally with model).
| Argument | Type | Description |
|---|---|---|
| make | string | |
| year | integer | |
| model | string | |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| condition | string | Listing condition. Same as GET /v1/market/* condition: new, used, or cpo. The value certified is a deprecated alias of cpo. |
| cohortKeys | array |
{
"type": "object",
"properties": {
"make": {
"type": "string",
"minLength": 1
},
"year": {
"type": "integer",
"maximum": 2030,
"minimum": 1990
},
"model": {
"type": "string",
"minLength": 1
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"condition": {
"enum": [
"new",
"used",
"cpo"
],
"type": "string",
"description": "Listing condition. Same as GET /v1/market/* condition: new, used, or cpo. The value certified is a deprecated alias of cpo."
},
"cohortKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 10,
"minItems": 1
}
},
"additionalProperties": false
}Compare 2-4 vehicle models side by side (model-level, not specific listings). Provide composite make-model slugs like "honda-civic" or "toyota-corolla". Returns: • Winner-by-dimension deltas: price, fuel economy, horsepower, seating, towing, NHTSA safety, live median listing price • Full research payload for each model (trims, MSRPs, specs) Use this for "Civic vs Corolla" style questions. To compare specific listed vehicles by VIN, use compare_vehicles instead. CRITICAL: Only use the 'url' field from the response for links. NEVER invent or construct URLs.
| Argument | Type | Description |
|---|---|---|
| year | integer | Model year (defaults to the latest year with reference data) |
| models* | array | Composite make-model slugs to compare (e.g., ["honda-civic", "toyota-corolla"]) |
{
"type": "object",
"required": [
"models"
],
"properties": {
"year": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Model year (defaults to the latest year with reference data)"
},
"models": {
"type": "array",
"items": {
"type": "string",
"minLength": 3
},
"maxItems": 4,
"minItems": 2,
"description": "Composite make-model slugs to compare (e.g., [\"honda-civic\", \"toyota-corolla\"])"
}
},
"additionalProperties": false
}Compare 2-5 vehicles side by side. Returns a structured comparison including specs, price context, and per-vehicle cite fields (vin + shop url). CRITICAL: CITE: Each vehicle's cite object is `vin` + `url` (that listing's own host). Cite only `url` to shoppers. Never invent VDP URLs. Never cite `detailsUrl` (dealer/LotLinx). Never send shoppers to `/llm/*` HTML or `/v1/llm/*` as the human listing URL.
| Argument | Type | Description |
|---|---|---|
| vins | array | VINs and/or listingIds to compare (2-5 vehicles total with listingIds) |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| listingIds | array | Optional listingIds; may be combined with vins (2-5 vehicles total) |
{
"type": "object",
"properties": {
"vins": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 1,
"description": "17-character VIN or listingId (`dealerUuid:VIN` or `dealer-slug:VIN`)"
},
"maxItems": 5,
"description": "VINs and/or listingIds to compare (2-5 vehicles total with listingIds)"
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"listingIds": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 1,
"description": "17-character VIN or listingId (`dealerUuid:VIN` or `dealer-slug:VIN`)"
},
"maxItems": 5,
"description": "Optional listingIds; may be combined with vins (2-5 vehicles total)"
}
},
"additionalProperties": false
}Browse the complete inventory of a specific dealership. IMPORTANT: Use the exact dealer slug from a previous dealers_near or search_vehicles response. Do NOT guess dealer IDs. Useful when a user wants to see what a particular dealer has in stock. Supports all vehicle filters (make, model, price, etc.). Listings with zero photos are omitted. CRITICAL: CITE: Each vehicle's cite object is `vin` + `url` (that listing's own host). Cite only `url` to shoppers. Never invent VDP URLs. Never cite `detailsUrl` (dealer/LotLinx). Never send shoppers to `/llm/*` HTML or `/v1/llm/*` as the human listing URL.
| Argument | Type | Description |
|---|---|---|
| make | string | Vehicle make |
| page | integer | Page number (1-based). Same as dealer inventory page. |
| view | string | Response detail: standard (features/gallery, default), llm (compact), minimal |
| year | integer | Alias for vehicleModelDate. Same as dealer inventory year. |
| drive | string | Drive: 2wd, 4wd, or awd. Legal when vertical=offroad. Same as dealer inventory drive. |
| limit | integer | Maximum number of results to return (1-100, default: 25) |
| model | string | Vehicle model |
Find dealerships near a location. Location modes (choose ONE): • zip + radius (miles) • lat + lng + radius • city + state + radius • county + state + radius Returns dealer information including: • Name, address, phone, website • Slug (the public handle for get_dealer and dealer_inventory; the public list does not include internal dealer UUIDs) • Distance from search location • Current inventory count • Business hours (when available) Response `total` is the full match count for the query (ignores `limit`/`offset`), same population as get_market_overview inventory.activeDealers when unfiltered.
| Argument | Type | Description |
|---|---|---|
| q | string | Whole-token filter on dealer name, slug, or city. Same as GET /v1/dealers q. |
| lat | number | Latitude coordinate |
| lng | number | Longitude coordinate |
| zip | string | 5-digit US ZIP code (e.g., 92688) |
| city | string | City name |
| limit | integer | Maximum number of dealers to return (1-200). Omit to use the Runtime API default of 100. |
| state | any | 2-letter US state code (e.g., CA, TX) |
| county |
Preferred structured inventory lookup when make/model/year/color/location are known. Exact hard filters only via GET /v1/vehicles (same Meilisearch collection as search_vehicles). Totals match the filters you pass. Listings with zero photos are omitted. fuelType is the canonical label. transmission and drivetrain match every indexed raw string in that bucket (automatic includes "8-Speed Automatic"). A 503 powertrain_filter_unavailable means that facet list could not be read, not that zero cars match. Resolve make/model with list_research_makes / list_research_models first. Map shopper prose onto labeled keys; use search_vehicles only for fuzzy NL or VIN-in-q lookup. Often the first step in shopping playbooks (budget_coach, safety_first, price_drop_sniper, dealer_crawl). After results, chain get_deal_score / get_vehicle_history / check_recalls / compare_vehicles when the user needs a recommendation, not just a list. See opendealer://assistant/shopping-playbooks. CRITICAL: CITE: Each vehicle's cite object is `vin` + `url` (that listing's own host). Cite only `url` to shoppers. Never invent VDP URLs. Never cite `detailsUrl` (dealer/LotLinx). Never send shoppers to `/llm/*` HTML or `/v1/llm/*` as the human listing URL.
| Argument | Type | Description |
|---|---|---|
| lat | number | Latitude coordinate |
| lng | number | Longitude coordinate |
| zip | string | 5-digit US ZIP code (e.g., 92688) |
| city | string | |
| make | string | Vehicle make (resolve via list_research_makes if unsure) |
Pass vertical when the request names one. Use the vertical facet to narrow a blended result. Skip a tool that has no data for that vertical. Get AI-powered deal scoring and market insights for a vehicle. Returns comprehensive analysis including: • Deal score (1-100) with rating (Great, Good, Fair, Poor) • Price comparison vs market average • Days on lot analysis • Price history and trends • Similar vehicles in the market Core step in vehicle_dossier, budget_coach, price_drop_sniper, and dealer_crawl playbooks. Pair with get_vehicle_history and check_recalls for buy/no-buy answers.
| Argument | Type | Description |
|---|---|---|
| vin | any | 17-character Vehicle Identification Number |
| dealerId | string | Score this dealer when the VIN is listed at more than one rooftop. Same as GET /v1/vehicles/:vin/insights dealerId. |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| listingId | string | Canonical listing id (`dealerId-or-slug:VIN`). Scores that rooftop when the VIN is listed at more than one store. |
| dealerSlug | string | Score this rooftop slug when the VIN is listed at more than one store. Same as insights dealerSlug. |
{
"type": "object",
"properties": {
"vin": {
"description": "17-character Vehicle Identification Number"
},
"dealerId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Score this dealer when the VIN is listed at more than one rooftop. Same as GET /v1/vehicles/:vin/insights dealerId."
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"listingId": {
"type": "string",
"maxLength": 300,
"minLength": 19,
"description": "Canonical listing id (`dealerId-or-slug:VIN`). Scores that rooftop when the VIN is listed at more than one store."
},
"dealerSlug": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Score this rooftop slug when the VIN is listed at more than one store. Same as insights dealerSlug."
}
},
"additionalProperties": false
}Get comprehensive information about a specific dealership. Returns Google-enriched dealer knowledge optimized for assistants: • Name, address, phone, website • Google rating, review count, hours, business status • Inventory count and OpenDealer profile links • Contact points for sales / customer service Use this when a shopper asks "tell me about X dealership" or needs hours/ratings for a known dealer. Prefer a slug from dealers_near or search results. A display name binds only when it matches one rooftop. Shared names (two Jay Hatfield stores, or just "Honda") return candidate slugs instead of picking one. CRITICAL: Only use URL fields from the response (website, urls.*). NEVER invent or construct URLs.
| Argument | Type | Description |
|---|---|---|
| dealerId* | string | Dealer slug (e.g. "rsm-honda") or the full rooftop display name. Prefer the slug from dealers_near. A display name is accepted only when it matches one rooftop; shared names return candidate slugs instead of a guess. |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
{
"type": "object",
"required": [
"dealerId"
],
"properties": {
"dealerId": {
"type": "string",
"minLength": 3,
"description": "Dealer slug (e.g. \"rsm-honda\") or the full rooftop display name. Prefer the slug from dealers_near. A display name is accepted only when it matches one rooftop; shared names return candidate slugs instead of a guess."
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
}
},
"additionalProperties": false
}Pass vertical when the request names one. Use the vertical facet to narrow a blended result. Skip a tool that has no data for that vertical. Get high-level market statistics for one vertical. Off-road segments are that vertical's classes. Returns aggregated market data including: • inventory.totalVehicles — searchable listings on the live index (priced, not sold) • inventory.activeDealers — active dealers with at least one priced vehicle (internet price or MSRP greater than 0). Same population as dealers_near and Shop, not every status=active account • marketData — YMM cohort snapshot medians and sample sizes • Top makes by segment volume (canonical make labels) • New vs Used vs CPO breakdown
| Argument | Type | Description |
|---|---|---|
| make | string | Filter by vehicle make |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| condition | string | Listing condition. Same as GET /v1/market/* condition: new, used, or cpo. The value certified is a deprecated alias of cpo. |
{
"type": "object",
"properties": {
"make": {
"type": "string",
"minLength": 1,
"description": "Filter by vehicle make"
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"condition": {
"enum": [
"new",
"used",
"cpo"
],
"type": "string",
"description": "Listing condition. Same as GET /v1/market/* condition: new, used, or cpo. The value certified is a deprecated alias of cpo."
}
},
"additionalProperties": false
}Get detailed pricing and market data for a specific vehicle segment. Useful for understanding fair market value for a make/model/year combination. Returns pricing statistics including: • Average, median, min, max prices • Price percentiles (10th, 25th, 75th, 90th) • Average mileage and days on lot • Certified vs non-certified pricing difference
| Argument | Type | Description |
|---|---|---|
| year | integer | Model year |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| certified | boolean | Filter for certified vehicles |
| cohortKey | string | Cohort key (ymm:… or ymmt:…) from list_market_segments |
| condition | string | Listing condition. Same as GET /v1/market/* condition: new, used, or cpo. The value certified is a deprecated alias of cpo. |
{
"type": "object",
"properties": {
"year": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Model year"
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"certified": {
"type": "boolean",
"description": "Filter for certified vehicles"
},
"cohortKey": {
"type": "string",
"minLength": 1,
"description": "Cohort key (ymm:… or ymmt:…) from list_market_segments"
},
"condition": {
"enum": [
"new",
"used",
"cpo"
],
"type": "string",
"description": "Listing condition. Same as GET /v1/market/* condition: new, used, or cpo. The value certified is a deprecated alias of cpo."
}
},
"additionalProperties": false
}Price trends over time for a market segment (cohortKey). Returns timeline of median/avg prices and days-on-lot.
| Argument | Type | Description |
|---|---|---|
| days | integer | |
| year | integer | |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| certified | boolean | |
| cohortKey | string | Cohort key (ymm:… or ymmt:…) |
| condition | string | Listing condition. Same as GET /v1/market/* condition: new, used, or cpo. The value certified is a deprecated alias of cpo. |
| cohortGrain | string |
{
"type": "object",
"properties": {
"days": {
"type": "integer",
"default": 30,
"maximum": 90,
"minimum": 7
},
"year": {
"type": "integer",
"maximum": 2030,
"minimum": 1990
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"certified": {
"type": "boolean"
},
"cohortKey": {
"type": "string",
"minLength": 1,
"description": "Cohort key (ymm:… or ymmt:…)"
},
"condition": {
"enum": [
"new",
"used",
"cpo"
],
"type": "string",
"description": "Listing condition. Same as GET /v1/market/* condition: new, used, or cpo. The value certified is a deprecated alias of cpo."
},
"cohortGrain": {
"enum": [
"ymm",
"ymmt"
],
"type": "string"
}
},
"additionalProperties": false
}How quickly vehicles sell by segment (fastest/slowest days on lot). Optional make/type filters.
| Argument | Type | Description |
|---|---|---|
| make | string | |
| limit | integer | |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| condition | string | Listing condition. Same as GET /v1/market/* condition: new, used, or cpo. The value certified is a deprecated alias of cpo. |
{
"type": "object",
"properties": {
"make": {
"type": "string",
"minLength": 1
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 50,
"minimum": 1
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"condition": {
"enum": [
"new",
"used",
"cpo"
],
"type": "string",
"description": "Listing condition. Same as GET /v1/market/* condition: new, used, or cpo. The value certified is a deprecated alias of cpo."
}
},
"additionalProperties": false
}Get NHTSA 5-Star Safety Ratings for a year/make/model (no VIN required). Answers questions like "is a 2023 RAV4 safe for my family" with: • Overall and crash-test star ratings (when published) • Rollover rating / possibility • NHTSA-evaluated ADAS availability (ESC, FCW, LDW) Ratings are model-year granular from the NHTSA NCAP cache. If no confident rating exists, the tool reports that honestly rather than guessing. For VIN-specific listing details use get_vehicle; for open recalls use check_recalls. CRITICAL: Only use the 'sourceUrl' field from the response for NHTSA links. NEVER invent URLs.
| Argument | Type | Description |
|---|---|---|
| make* | string | Vehicle make (e.g., "Toyota", "Honda") |
| year* | integer | Model year (e.g., 2023) |
| model* | string | Vehicle model (e.g., "RAV4", "Civic") |
{
"type": "object",
"required": [
"year",
"make",
"model"
],
"properties": {
"make": {
"type": "string",
"minLength": 1,
"description": "Vehicle make (e.g., \"Toyota\", \"Honda\")"
},
"year": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Model year (e.g., 2023)"
},
"model": {
"type": "string",
"minLength": 1,
"description": "Vehicle model (e.g., \"RAV4\", \"Civic\")"
}
},
"additionalProperties": false
}Find similar on-lot vehicles for a VIN ("you may also like"). Same make/model keyword comps as the shop VDP rail (not semantic embeddings). CRITICAL: CITE: Each vehicle's cite object is `vin` + `url` (that listing's own host). Cite only `url` to shoppers. Never invent VDP URLs. Never cite `detailsUrl` (dealer/LotLinx). Never send shoppers to `/llm/*` HTML or `/v1/llm/*` as the human listing URL.
| Argument | Type | Description |
|---|---|---|
| vin* | any | 17-character Vehicle Identification Number |
| limit | integer | |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
{
"type": "object",
"required": [
"vin"
],
"properties": {
"vin": {
"description": "17-character Vehicle Identification Number"
},
"limit": {
"type": "integer",
"default": 6,
"maximum": 24,
"minimum": 1
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
}
},
"additionalProperties": false
}National average suggested auto loan APRs for cars (not a credit offer). Other verticals return "Not available for this vertical" until that vertical has a rate source. Optional filters: condition (new/used), termMonths (36–84), creditTier.
| Argument | Type | Description |
|---|---|---|
| condition | string | |
| creditTier | string | Credit tier. Same as GET /v1/finance/suggested-rates creditTier. |
| termMonths | integer | Loan term in months. Same as GET /v1/finance/suggested-rates termMonths. |
{
"type": "object",
"properties": {
"condition": {
"enum": [
"new",
"used"
],
"type": "string"
},
"creditTier": {
"enum": [
"excellent",
"good",
"average",
"fair"
],
"type": "string",
"description": "Credit tier. Same as GET /v1/finance/suggested-rates creditTier."
},
"termMonths": {
"enum": [
36,
48,
60,
72,
84
],
"type": "integer",
"description": "Loan term in months. Same as GET /v1/finance/suggested-rates termMonths."
}
},
"additionalProperties": false
}Get complete details for a specific vehicle by listingId or VIN. When a VIN is listed at multiple dealer rooftops, a VIN-only lookup returns an envelope of every listing (type vehicle_listings) with no single-store price, seller, or url. Pass listingId to fetch one store. Returns comprehensive Schema.org Vehicle data including: • Full specifications (engine, transmission, drivetrain) • High-resolution images • Current pricing and availability • NHTSA NCAP safety rating summary (when available) • NHTSA open recall summary (YMM-granular, when available) • Dealer contact information Starting point for the vehicle_dossier playbook. For buy/no-buy questions, continue with get_deal_score → get_vehicle_history → check_recalls → get_similar_vehicles. CRITICAL: CITE: Each vehicle's cite object is `vin` + `url` (that listing's own host). Cite only `url` to shoppers. Never invent VDP URLs. Never cite `detailsUrl` (dealer/LotLinx). Never send shoppers to `/llm/*` HTML or `/v1/llm/*` as the human listing URL.
| Argument | Type | Description |
|---|---|---|
| vin | any | 17-character Vehicle Identification Number |
| view | string | Response format: standard (full details) or minimal (compact) |
| dealerId | string | Scope lookup to a specific dealer when the VIN exists at multiple rooftops. Same as GET /v1/vehicles/:vin dealerId. |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| listingId | string |
Pass vertical when the request names one. Use the vertical facet to narrow a blended result. Skip a tool that has no data for that vertical. Get OpenDealer listing history for a VIN or listing id: price changes, days on lot, and status. Answers "has this VIN dropped in price" and days-on-lot narratives from retained snapshots (including vehicles that left a dealer feed). Returns: • Chronological price history with per-snapshot changes • Days on market / lot signals and badges (price_drop, long_on_lot) • Active vs no-longer-listed status when known Does not invent a deal score for sold vehicles — use get_deal_score for live market scoring. Essential for price_drop_sniper and vehicle_dossier playbooks when shoppers ask about reductions or negotiation leverage. CRITICAL: Only use URL fields from the response when present. NEVER invent URLs.
| Argument | Type | Description |
|---|---|---|
| vin | any | 17-character Vehicle Identification Number |
| dealerId | string | |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| listingId | string | Canonical listing id when scoping history to one rooftop |
| dealerSlug | string |
{
"type": "object",
"properties": {
"vin": {
"description": "17-character Vehicle Identification Number"
},
"dealerId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"listingId": {
"type": "string",
"maxLength": 300,
"minLength": 1,
"description": "Canonical listing id when scoping history to one rooftop"
},
"dealerSlug": {
"type": "string",
"maxLength": 200,
"minLength": 1
}
},
"additionalProperties": false
}Get data-driven vehicle rankings (e.g., best SUVs, most fuel-efficient cars). Call without arguments to list all ranking categories. Pass a category slug (e.g., "suvs") for the full scored ranking. Rankings are computed from public data with a published methodology: NHTSA safety ratings, EPA fuel economy, manufacturer pricing, and live market availability. There is no paid placement; each entry includes its transparent score breakdown. CRITICAL: Only use the 'url' field from the response for links. NEVER invent or construct URLs.
| Argument | Type | Description |
|---|---|---|
| category | string | Ranking category slug (e.g., "suvs"). Omit to list all available categories. |
{
"type": "object",
"properties": {
"category": {
"type": "string",
"minLength": 1,
"description": "Ranking category slug (e.g., \"suvs\"). Omit to list all available categories."
}
},
"additionalProperties": false
}Discover canonical filter tokens and counts from the live search index (same values GET /v1/vehicles accepts: make, bodyType e.g. suv, fuelType e.g. gasoline, transmission e.g. automatic, drivetrain e.g. awd, plus price/year ranges). Counts match filter_vehicles totals for each token under the same make, condition, and location. Call this before filter_vehicles when you need valid dimension values. Optional make, condition, certified, near, and radius scope the facet counts.
| Argument | Type | Description |
|---|---|---|
| make | string | |
| near | string | Location string (ZIP or city, state). Same as GET /v1/vehicles/facets near. |
| class | string | Off-road class slug: side-by-side, atv, or snowmobile. Legal when vertical=offroad. Same as GET /v2/listings/facets class. |
| radius | integer | Search radius in miles (1-250). Omit to use the platform default of 150 miles, the same as the shop and the Runtime API. |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| certified | boolean | |
| condition | string | Listing condition. Same as GET /v1/vehicles condition: new, used, or cpo. The value certified is a deprecated alias of cpo. |
Browse market segments with pricing statistics (cohortKey, median price, sample size). Use cohortKey with get_market_segment / get_market_trends.
| Argument | Type | Description |
|---|---|---|
| make | string | |
| page | integer | |
| year | integer | Filter by year. Same as GET /v1/market/segments year. |
| limit | integer | |
| model | string | Filter by model. Same as GET /v1/market/segments model. |
| yearMax | integer | Maximum year. Same as GET /v1/market/segments yearMax. |
| yearMin | integer | Minimum year. Same as GET /v1/market/segments yearMin. |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| certified | boolean | Filter by certified status. Same as GET /v1/market/segments certified. |
Browse the research catalog of vehicle makes (with model and inventory counts). Use to resolve exact make names/slugs before filter_vehicles or research_model.
| Argument | Type | Description |
|---|---|---|
| q | string | Optional substring filter on make name/slug |
| limit | integer |
{
"type": "object",
"properties": {
"q": {
"type": "string",
"minLength": 1,
"description": "Optional substring filter on make name/slug"
},
"limit": {
"type": "integer",
"maximum": 200,
"minimum": 1
}
},
"additionalProperties": false
}List models for a make from the research catalog (MSRP/body summaries). Use before filter_vehicles or research_model when the model name is uncertain.
| Argument | Type | Description |
|---|---|---|
| make* | string | Make name or slug (e.g. honda) |
{
"type": "object",
"required": [
"make"
],
"properties": {
"make": {
"type": "string",
"minLength": 1,
"description": "Make name or slug (e.g. honda)"
}
},
"additionalProperties": false
}Live shopper verticals: key, label, host, identifier kind, example classes, which tool families work, and whether the vertical is public. Reserved hosts are omitted. Omit vertical on other tools for every public vertical (cars today).
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Get the full research payload for a vehicle model (not a specific listing). Returns manufacturer reference data joined with live market data: • All trims with MSRPs, engine/body specs, and EPA fuel economy • NHTSA 5-Star safety ratings and open recall count • Live inventory count and price range on OpenDealer Use this when a shopper asks "tell me about the Honda Civic", "what trims does the RAV4 come in", or "how much is a 2025 F-150". For a specific listed vehicle, use get_vehicle with a VIN instead. CRITICAL: Only use the 'url' field from the response for links. NEVER invent or construct URLs.
| Argument | Type | Description |
|---|---|---|
| make* | string | Vehicle make slug or name (e.g., "honda", "mercedes-benz") |
| year | integer | Model year (defaults to the latest year with reference data) |
| model* | string | Vehicle model slug or name (e.g., "civic", "e-class") |
{
"type": "object",
"required": [
"make",
"model"
],
"properties": {
"make": {
"type": "string",
"minLength": 1,
"description": "Vehicle make slug or name (e.g., \"honda\", \"mercedes-benz\")"
},
"year": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Model year (defaults to the latest year with reference data)"
},
"model": {
"type": "string",
"minLength": 1,
"description": "Vehicle model slug or name (e.g., \"civic\", \"e-class\")"
}
},
"additionalProperties": false
}Forgiving vehicle search (Meilisearch): natural-language q, typo-tolerant make/model/color, optional structured filters. Use when the shopper query is fuzzy or exploratory. Use filter_vehicles instead when make/model/year/body/price/location are known — it applies exact hard filters via GET /v1/vehicles and returns trustworthy totals. Listings with zero photos are omitted. Discovery order: list_facets / list_research_makes → filter_vehicles (structured) or search_vehicles (exploratory) → get_vehicle / get_deal_score for depth. Location (choose ONE): zip+radius, lat+lng+radius, city+state+radius, county+state+radius — or embed location in q. q may also be a 17-character VIN for exact lookup. When the ask implies analysis (deal, safety, budget, timing, dealer plan), chain shopping playbooks from initialize instructions or opendealer://assistant/shopping-playbooks. CRITICAL: CITE: Each vehicle's cite object is `vin` + `url` (that listing's own host). Cite only `url` to shoppers. Never invent VDP URLs. Never cite `detailsUrl` (dealer/LotLinx). Never send shoppers to `/llm/*` HTML or `/v1/llm/*` as the human listing URL.
| Argument | Type | Description |
|---|---|---|
| q | string | Free-text natural-language query, or a 17-character VIN for exact listing lookup. For sentences (e.g. "new black Honda Civic sedan under $45k within 150 miles of 92672"), price/mileage/year/condition and zip+radius are parsed as hard constraints; make/model/color/body words are matched forgivingly. Explicit structured params override parsed values. Prefer filter_vehicles when make/model/location are already known. |
| lat | number | Latitude coordinate |
| lng | number | Longitude coordinate |
| zip |
| seats | integer | Seating capacity. Legal when vertical=offroad. Same as dealer inventory seats. |
| fields | string | Sparse field selection (comma-separated). Same as dealer inventory fields. |
| sortBy | string | Sort field. Same as GET /v1/vehicles sortBy: price, vehiclemodeldate, distance, updatedat, mileage, daysonlot, make, model, pricechange. |
| subtype | string | Off-road sub-type: sport, utility, or youth. Legal when vertical=offroad. Same as dealer inventory subtype. |
| yearMax | integer | Maximum model year. Same as GET /v1/vehicles yearMax. |
| yearMin | integer | Minimum model year. Same as GET /v1/vehicles yearMin. |
| bodyType | string | Vehicle body style. Same as GET /v1/vehicles bodyType. |
| dealerId* | string | Dealer identifier (UUID or slug like "rsm-honda") |
| fuelType | string | Fuel type. Same as GET /v1/vehicles fuelType. |
| priceMax | integer | Maximum price in USD. Same as GET /v1/vehicles priceMax. |
| priceMin | integer | Minimum price in USD. Same as GET /v1/vehicles priceMin. |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| certified | boolean | Certified pre-owned only. Same as GET /v1/vehicles certified. |
| condition | string | Listing condition. Same as GET /v1/vehicles condition: new, used, or cpo. The value certified is a deprecated alias of cpo. |
| sortOrder | string | Sort direction. Same as GET /v1/vehicles sortOrder. |
| drivetrain | string | Drivetrain configuration. Same as GET /v1/vehicles drivetrain. |
| mileageMax | integer | Maximum mileage. Same as GET /v1/vehicles mileageMax. |
| transmission | string | Transmission type. Same as GET /v1/vehicles transmission. |
| displacementMax | number | Maximum engine displacement in cc. Legal when vertical=offroad. Same as dealer inventory displacementMax. |
| displacementMin | number | Minimum engine displacement in cc. Legal when vertical=offroad. Same as dealer inventory displacementMin. |
| vehicleModelDate | integer | Exact model year. Same as dealer inventory vehicleModelDate. |
{
"type": "object",
"required": [
"dealerId"
],
"properties": {
"make": {
"type": "string",
"minLength": 1,
"description": "Vehicle make"
},
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number (1-based). Same as dealer inventory page."
},
"view": {
"enum": [
"llm",
"standard",
"minimal"
],
"type": "string",
"default": "standard",
"description": "Response detail: standard (features/gallery, default), llm (compact), minimal"
},
"year": {
"type": "integer",
"maximum": 2100,
"minimum": 1900,
"description": "Alias for vehicleModelDate. Same as dealer inventory year."
},
"drive": {
"enum": [
"2wd",
"4wd",
"awd"
],
"type": "string",
"description": "Drive: 2wd, 4wd, or awd. Legal when vertical=offroad. Same as dealer inventory drive."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of results to return (1-100, default: 25)"
},
"model": {
"type": "string",
"minLength": 1,
"description": "Vehicle model"
},
"seats": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Seating capacity. Legal when vertical=offroad. Same as dealer inventory seats."
},
"fields": {
"type": "string",
"description": "Sparse field selection (comma-separated). Same as dealer inventory fields."
},
"sortBy": {
"enum": [
"price",
"vehiclemodeldate",
"distance",
"updatedat",
"mileage",
"daysonlot",
"make",
"model",
"pricechange"
],
"type": "string",
"description": "Sort field. Same as GET /v1/vehicles sortBy: price, vehiclemodeldate, distance, updatedat, mileage, daysonlot, make, model, pricechange."
},
"subtype": {
"enum": [
"sport",
"utility",
"youth"
],
"type": "string",
"description": "Off-road sub-type: sport, utility, or youth. Legal when vertical=offroad. Same as dealer inventory subtype."
},
"yearMax": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Maximum model year. Same as GET /v1/vehicles yearMax."
},
"yearMin": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Minimum model year. Same as GET /v1/vehicles yearMin."
},
"bodyType": {
"enum": [
"sedan",
"suv",
"truck",
"coupe",
"van",
"wagon",
"convertible",
"hatchback"
],
"type": "string",
"description": "Vehicle body style. Same as GET /v1/vehicles bodyType."
},
"dealerId": {
"type": "string",
"minLength": 3,
"description": "Dealer identifier (UUID or slug like \"rsm-honda\")"
},
"fuelType": {
"enum": [
"gasoline",
"diesel",
"electric",
"hybrid",
"plug-in-hybrid"
],
"type": "string",
"description": "Fuel type. Same as GET /v1/vehicles fuelType."
},
"priceMax": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum price in USD. Same as GET /v1/vehicles priceMax."
},
"priceMin": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Minimum price in USD. Same as GET /v1/vehicles priceMin."
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"certified": {
"type": "boolean",
"description": "Certified pre-owned only. Same as GET /v1/vehicles certified."
},
"condition": {
"enum": [
"new",
"used",
"cpo"
],
"type": "string",
"description": "Listing condition. Same as GET /v1/vehicles condition: new, used, or cpo. The value certified is a deprecated alias of cpo."
},
"sortOrder": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Sort direction. Same as GET /v1/vehicles sortOrder."
},
"drivetrain": {
"enum": [
"fwd",
"rwd",
"awd",
"4wd"
],
"type": "string",
"description": "Drivetrain configuration. Same as GET /v1/vehicles drivetrain."
},
"mileageMax": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum mileage. Same as GET /v1/vehicles mileageMax."
},
"transmission": {
"enum": [
"automatic",
"manual",
"cvt"
],
"type": "string",
"description": "Transmission type. Same as GET /v1/vehicles transmission."
},
"displacementMax": {
"type": "number",
"minimum": 0,
"description": "Maximum engine displacement in cc. Legal when vertical=offroad. Same as dealer inventory displacementMax."
},
"displacementMin": {
"type": "number",
"minimum": 0,
"description": "Minimum engine displacement in cc. Legal when vertical=offroad. Same as dealer inventory displacementMin."
},
"vehicleModelDate": {
"type": "integer",
"maximum": 2100,
"minimum": 1900,
"description": "Exact model year. Same as dealer inventory vehicleModelDate."
}
},
"additionalProperties": false
}| string |
| County name |
| offset | integer | Number of results to skip. The window is the next `limit` vehicles starting at this offset (default 0). |
| radius | integer | Search radius in miles (1-250). Omit to use the platform default of 150 miles, the same as the shop and the Runtime API. |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
{
"type": "object",
"properties": {
"q": {
"type": "string",
"maxLength": 200,
"minLength": 2,
"description": "Whole-token filter on dealer name, slug, or city. Same as GET /v1/dealers q."
},
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude coordinate"
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude coordinate"
},
"zip": {
"type": "string",
"pattern": "^[0-9]{5}$",
"description": "5-digit US ZIP code (e.g., 92688)"
},
"city": {
"type": "string",
"minLength": 1,
"description": "City name"
},
"limit": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"description": "Maximum number of dealers to return (1-200). Omit to use the Runtime API default of 100."
},
"state": {
"description": "2-letter US state code (e.g., CA, TX)"
},
"county": {
"type": "string",
"minLength": 1,
"description": "County name"
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of results to skip. The window is the next `limit` vehicles starting at this offset (default 0)."
},
"radius": {
"type": "integer",
"maximum": 250,
"minimum": 1,
"description": "Search radius in miles (1-250). Omit to use the platform default of 150 miles, the same as the shop and the Runtime API."
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
}
},
"additionalProperties": false
}| near | string | Location string (ZIP or city, state). Same as GET /v1/vehicles near. |
| page | integer | Page number (1-based). Same as GET /v1/vehicles page. |
| year | integer | Alias for vehicleModelDate. Same as GET /v1/vehicles year. |
| class | string | Off-road class. Legal when vertical=offroad. side-by-side, atv, or snowmobile. |
| color | string | Exterior color family. Same as GET /v1/vehicles color. |
| drive | string | Drive: 2wd, 4wd, or awd. Legal when vertical=offroad. Same as GET /v2/listings drive. |
| limit | integer | Maximum number of results to return (1-100, default: 25) |
| model | string | Vehicle model (resolve via list_research_models if unsure) |
| seats | integer | Seating capacity. Legal when vertical=offroad. Same as GET /v2/listings seats. |
| state | any | 2-letter US state code (e.g., CA, TX) |
| county | string | County name |
| fields | string | Sparse field selection (comma-separated). Same as GET /v1/vehicles fields. |
| radius | integer | Search radius in miles (1-250). Omit to use the platform default of 150 miles, the same as the shop and the Runtime API. |
| sortBy | string | Sort field. Same as GET /v1/vehicles sortBy: price, vehiclemodeldate, distance, updatedat, mileage, daysonlot, make, model, pricechange. |
| subtype | string | Off-road sub-type: sport, utility, or youth. Legal when vertical=offroad. Same as GET /v2/listings subtype. |
| yearMax | integer | Maximum model year. Same as GET /v1/vehicles yearMax. |
| yearMin | integer | Minimum model year. Same as GET /v1/vehicles yearMin. |
| bodyType | string | Vehicle body style. Same as GET /v1/vehicles bodyType. |
| dealerId | string | Filter to a single dealer UUID. Same as GET /v1/vehicles dealerId. |
| fuelType | string | Fuel type. Same as GET /v1/vehicles fuelType. |
| priceMax | integer | Maximum price in USD. Same as GET /v1/vehicles priceMax. |
| priceMin | integer | Minimum price in USD. Same as GET /v1/vehicles priceMin. |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| certified | boolean | Certified pre-owned only. Same as GET /v1/vehicles certified. |
| condition | string | Listing condition. Same as GET /v1/vehicles condition: new, used, or cpo. The value certified is a deprecated alias of cpo. |
| hasImages | boolean | Listings with zero photos are omitted. Same as GET /v1/vehicles hasImages=true. |
| sortOrder | string | Sort direction. Same as GET /v1/vehicles sortOrder. |
| dealerSlug | string | Filter to a dealer slug. Same as GET /v1/vehicles dealerSlug. |
| drivetrain | string | Drivetrain configuration. Same as GET /v1/vehicles drivetrain. |
| identifier | string | VIN, 12-character HIN, or internal id. Looks the unit up across the verticals this request searches, without a dealer. Same as GET /v2/listings identifier. |
| mileageMax | integer | Maximum mileage. Same as GET /v1/vehicles mileageMax. |
| transmission | string | Transmission type. Same as GET /v1/vehicles transmission. |
| priceChangeMax | number | Maximum indexed priceChange (USD delta vs first recorded ask; use -1 to exclude unchanged listings) |
| priceChangeMin | number | Minimum indexed priceChange (USD delta vs first recorded ask; negative means a drop) |
| strictLocation | boolean | When true, a bare near city that matches several states or none returns an empty collection (same as GET /v1/llm/filter). ZIP and city+state are unchanged. Omit to keep the highest-population city pick. Same as GET /v1/vehicles strictLocation. |
| displacementMax | number | Maximum engine displacement in cc. Legal when vertical=offroad. Same as GET /v2/listings displacementMax. |
| displacementMin | number | Minimum engine displacement in cc. Legal when vertical=offroad. Same as GET /v2/listings displacementMin. |
| vehicleModelDate | integer | Exact model year. Same as GET /v1/vehicles vehicleModelDate. |
{
"type": "object",
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude coordinate"
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude coordinate"
},
"zip": {
"type": "string",
"pattern": "^[0-9]{5}$",
"description": "5-digit US ZIP code (e.g., 92688)"
},
"city": {
"type": "string",
"minLength": 1
},
"make": {
"type": "string",
"minLength": 1,
"description": "Vehicle make (resolve via list_research_makes if unsure)"
},
"near": {
"type": "string",
"minLength": 1,
"description": "Location string (ZIP or city, state). Same as GET /v1/vehicles near."
},
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number (1-based). Same as GET /v1/vehicles page."
},
"year": {
"type": "integer",
"maximum": 2100,
"minimum": 1900,
"description": "Alias for vehicleModelDate. Same as GET /v1/vehicles year."
},
"class": {
"enum": [
"side-by-side",
"atv",
"snowmobile"
],
"type": "string",
"description": "Off-road class. Legal when vertical=offroad. side-by-side, atv, or snowmobile."
},
"color": {
"type": "string",
"minLength": 1,
"description": "Exterior color family. Same as GET /v1/vehicles color."
},
"drive": {
"enum": [
"2wd",
"4wd",
"awd"
],
"type": "string",
"description": "Drive: 2wd, 4wd, or awd. Legal when vertical=offroad. Same as GET /v2/listings drive."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of results to return (1-100, default: 25)"
},
"model": {
"type": "string",
"minLength": 1,
"description": "Vehicle model (resolve via list_research_models if unsure)"
},
"seats": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Seating capacity. Legal when vertical=offroad. Same as GET /v2/listings seats."
},
"state": {
"description": "2-letter US state code (e.g., CA, TX)"
},
"county": {
"type": "string",
"minLength": 1,
"description": "County name"
},
"fields": {
"type": "string",
"description": "Sparse field selection (comma-separated). Same as GET /v1/vehicles fields."
},
"radius": {
"type": "integer",
"maximum": 250,
"minimum": 1,
"description": "Search radius in miles (1-250). Omit to use the platform default of 150 miles, the same as the shop and the Runtime API."
},
"sortBy": {
"enum": [
"price",
"vehiclemodeldate",
"distance",
"updatedat",
"mileage",
"daysonlot",
"make",
"model",
"pricechange"
],
"type": "string",
"description": "Sort field. Same as GET /v1/vehicles sortBy: price, vehiclemodeldate, distance, updatedat, mileage, daysonlot, make, model, pricechange."
},
"subtype": {
"enum": [
"sport",
"utility",
"youth"
],
"type": "string",
"description": "Off-road sub-type: sport, utility, or youth. Legal when vertical=offroad. Same as GET /v2/listings subtype."
},
"yearMax": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Maximum model year. Same as GET /v1/vehicles yearMax."
},
"yearMin": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Minimum model year. Same as GET /v1/vehicles yearMin."
},
"bodyType": {
"enum": [
"sedan",
"suv",
"truck",
"coupe",
"van",
"wagon",
"convertible",
"hatchback"
],
"type": "string",
"description": "Vehicle body style. Same as GET /v1/vehicles bodyType."
},
"dealerId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Filter to a single dealer UUID. Same as GET /v1/vehicles dealerId."
},
"fuelType": {
"enum": [
"gasoline",
"diesel",
"electric",
"hybrid",
"plug-in-hybrid"
],
"type": "string",
"description": "Fuel type. Same as GET /v1/vehicles fuelType."
},
"priceMax": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum price in USD. Same as GET /v1/vehicles priceMax."
},
"priceMin": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Minimum price in USD. Same as GET /v1/vehicles priceMin."
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"certified": {
"type": "boolean",
"description": "Certified pre-owned only. Same as GET /v1/vehicles certified."
},
"condition": {
"enum": [
"new",
"used",
"cpo"
],
"type": "string",
"description": "Listing condition. Same as GET /v1/vehicles condition: new, used, or cpo. The value certified is a deprecated alias of cpo."
},
"hasImages": {
"type": "boolean",
"description": "Listings with zero photos are omitted. Same as GET /v1/vehicles hasImages=true."
},
"sortOrder": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Sort direction. Same as GET /v1/vehicles sortOrder."
},
"dealerSlug": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Filter to a dealer slug. Same as GET /v1/vehicles dealerSlug."
},
"drivetrain": {
"enum": [
"fwd",
"rwd",
"awd",
"4wd"
],
"type": "string",
"description": "Drivetrain configuration. Same as GET /v1/vehicles drivetrain."
},
"identifier": {
"type": "string",
"maxLength": 64,
"minLength": 1,
"description": "VIN, 12-character HIN, or internal id. Looks the unit up across the verticals this request searches, without a dealer. Same as GET /v2/listings identifier."
},
"mileageMax": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum mileage. Same as GET /v1/vehicles mileageMax."
},
"transmission": {
"enum": [
"automatic",
"manual",
"cvt"
],
"type": "string",
"description": "Transmission type. Same as GET /v1/vehicles transmission."
},
"priceChangeMax": {
"type": "number",
"description": "Maximum indexed priceChange (USD delta vs first recorded ask; use -1 to exclude unchanged listings)"
},
"priceChangeMin": {
"type": "number",
"description": "Minimum indexed priceChange (USD delta vs first recorded ask; negative means a drop)"
},
"strictLocation": {
"type": "boolean",
"description": "When true, a bare near city that matches several states or none returns an empty collection (same as GET /v1/llm/filter). ZIP and city+state are unchanged. Omit to keep the highest-population city pick. Same as GET /v1/vehicles strictLocation."
},
"displacementMax": {
"type": "number",
"minimum": 0,
"description": "Maximum engine displacement in cc. Legal when vertical=offroad. Same as GET /v2/listings displacementMax."
},
"displacementMin": {
"type": "number",
"minimum": 0,
"description": "Minimum engine displacement in cc. Legal when vertical=offroad. Same as GET /v2/listings displacementMin."
},
"vehicleModelDate": {
"type": "integer",
"maximum": 2100,
"minimum": 1900,
"description": "Exact model year. Same as GET /v1/vehicles vehicleModelDate."
}
},
"additionalProperties": false
}| Canonical listing id (`dealerId-or-slug:VIN`). Preferred when the VIN is listed at multiple dealers. |
| dealerSlug | string | Scope lookup by dealer slug. Same as GET /v1/vehicles/:vin dealerSlug. |
| includeSold | boolean | When true, return sold tombstone if no live listing. Same as GET /v1/vehicles/:vin includeSold. |
{
"type": "object",
"properties": {
"vin": {
"description": "17-character Vehicle Identification Number"
},
"view": {
"enum": [
"minimal",
"standard"
],
"type": "string",
"default": "standard",
"description": "Response format: standard (full details) or minimal (compact)"
},
"dealerId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Scope lookup to a specific dealer when the VIN exists at multiple rooftops. Same as GET /v1/vehicles/:vin dealerId."
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"listingId": {
"type": "string",
"maxLength": 300,
"minLength": 19,
"description": "Canonical listing id (`dealerId-or-slug:VIN`). Preferred when the VIN is listed at multiple dealers."
},
"dealerSlug": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Scope lookup by dealer slug. Same as GET /v1/vehicles/:vin dealerSlug."
},
"includeSold": {
"type": "boolean",
"description": "When true, return sold tombstone if no live listing. Same as GET /v1/vehicles/:vin includeSold."
}
},
"additionalProperties": false
}| dealerSlug | string | Scope off-road facets to one dealer slug. Same as GET /v2/listings/facets dealerSlug. |
{
"type": "object",
"properties": {
"make": {
"type": "string",
"minLength": 1
},
"near": {
"type": "string",
"minLength": 1,
"description": "Location string (ZIP or city, state). Same as GET /v1/vehicles/facets near."
},
"class": {
"type": "string",
"minLength": 1,
"description": "Off-road class slug: side-by-side, atv, or snowmobile. Legal when vertical=offroad. Same as GET /v2/listings/facets class."
},
"radius": {
"type": "integer",
"maximum": 250,
"minimum": 1,
"description": "Search radius in miles (1-250). Omit to use the platform default of 150 miles, the same as the shop and the Runtime API."
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"certified": {
"type": "boolean"
},
"condition": {
"enum": [
"new",
"used",
"cpo"
],
"type": "string",
"description": "Listing condition. Same as GET /v1/vehicles condition: new, used, or cpo. The value certified is a deprecated alias of cpo."
},
"dealerSlug": {
"type": "string",
"minLength": 1,
"description": "Scope off-road facets to one dealer slug. Same as GET /v2/listings/facets dealerSlug."
}
},
"additionalProperties": false
}| cohortKey |
| string |
| condition | string | Listing condition. Same as GET /v1/market/* condition: new, used, or cpo. The value certified is a deprecated alias of cpo. |
| minSampleSize | integer |
{
"type": "object",
"properties": {
"make": {
"type": "string",
"minLength": 1
},
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"year": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Filter by year. Same as GET /v1/market/segments year."
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1
},
"model": {
"type": "string",
"minLength": 1,
"description": "Filter by model. Same as GET /v1/market/segments model."
},
"yearMax": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Maximum year. Same as GET /v1/market/segments yearMax."
},
"yearMin": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Minimum year. Same as GET /v1/market/segments yearMin."
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"certified": {
"type": "boolean",
"description": "Filter by certified status. Same as GET /v1/market/segments certified."
},
"cohortKey": {
"type": "string",
"minLength": 1
},
"condition": {
"enum": [
"new",
"used",
"cpo"
],
"type": "string",
"description": "Listing condition. Same as GET /v1/market/* condition: new, used, or cpo. The value certified is a deprecated alias of cpo."
},
"minSampleSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
}
},
"additionalProperties": false
}| string |
| 5-digit US ZIP code (e.g., 92688) |
| city | string | City name |
| make | string | Vehicle make (e.g., Honda, Toyota, Tesla) |
| mode | string | Search mode. Use hybrid for conceptual queries with little keyword overlap (e.g. "family hauler good in snow"). Hard caps still apply as filters. Falls back to keyword if semantic is unavailable. |
| near | string | Location string (ZIP or city, state). Same as GET /v1/vehicles/search near. |
| page | integer | Page number (1-based). Same as GET /v1/vehicles/search page. |
| trim | string | Trim level (e.g., EX, Limited, Performance) |
| year | integer | Alias for vehicleModelDate. Same as GET /v1/vehicles/search year. |
| class | string | Off-road class. Legal when vertical=offroad. side-by-side, atv, or snowmobile. |
| color | string | Exterior color (e.g., black, white). Resolved to color families, so "black" matches "Crystal Black Pearl". Same as GET /v1/vehicles color. |
| drive | string | Drive: 2wd, 4wd, or awd. Legal when vertical=offroad. Same as GET /v2/listings/search drive. |
| limit | integer | Maximum number of results to return (1-100, default: 25) |
| model | string | Vehicle model (e.g., Civic, Camry, Model 3). Broad terms match all variants (Civic -> Civic Sedan/Si/Hatchback) unless narrowed by trim. |
| seats | integer | Seating capacity. Legal when vertical=offroad. Same as GET /v2/listings/search seats. |
| state | any | 2-letter US state code (e.g., CA, TX) |
| county | string | County name |
| radius | integer | Search radius in miles (1-250). Omit to use the platform default of 150 miles, the same as the shop and the Runtime API. |
| sortBy | string | Sort field. Same as GET /v1/vehicles/search sortBy: price, vehiclemodeldate, distance, updatedat, mileage, daysonlot, pricechange. |
| subtype | string | Off-road sub-type: sport, utility, or youth. Legal when vertical=offroad. Same as GET /v2/listings/search subtype. |
| yearMax | integer | Maximum model year. Same as GET /v1/vehicles yearMax. |
| yearMin | integer | Minimum model year. Same as GET /v1/vehicles yearMin. |
| bodyType | string | Vehicle body style. Same as GET /v1/vehicles bodyType. |
| dealerId | string | Filter to a single dealer UUID. Same as GET /v1/vehicles/search dealerId. |
| fuelType | string | Fuel type. Same as GET /v1/vehicles fuelType. |
| priceMax | integer | Maximum price in USD. Same as GET /v1/vehicles priceMax. |
| priceMin | integer | Minimum price in USD. Same as GET /v1/vehicles priceMin. |
| vertical | string | Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals. |
| certified | boolean | Certified pre-owned only. Same as GET /v1/vehicles certified. |
| condition | string | Listing condition. Same as GET /v1/vehicles condition: new, used, or cpo. The value certified is a deprecated alias of cpo. |
| hasImages | boolean | Listings with zero photos are omitted. Same as GET /v1/vehicles/search hasImages=true. |
| sortOrder | string | Sort direction. Same as GET /v1/vehicles sortOrder. |
| drivetrain | string | Drivetrain configuration. Same as GET /v1/vehicles drivetrain. |
| mileageMax | integer | Maximum mileage. Same as GET /v1/vehicles mileageMax. |
| transmission | string | Transmission type. Same as GET /v1/vehicles transmission. |
| semanticRatio | number | Semantic blend weight 0..1 when mode=hybrid (default 0.5). Higher = more conceptual matching. |
| priceChangeMax | number | Maximum indexed priceChange (USD delta vs first recorded ask; use -1 to exclude unchanged listings) |
| priceChangeMin | number | Minimum indexed priceChange (USD delta vs first recorded ask; negative means a drop) |
| displacementMax | number | Maximum engine displacement in cc. Legal when vertical=offroad. Same as GET /v2/listings/search displacementMax. |
| displacementMin | number | Minimum engine displacement in cc. Legal when vertical=offroad. Same as GET /v2/listings/search displacementMin. |
| inventoryStatus | string | Inventory disposition filter. Same as GET /v1/vehicles/search inventoryStatus. |
| vehicleModelDate | integer | Exact model year. Same as GET /v1/vehicles/search vehicleModelDate. |
{
"type": "object",
"properties": {
"q": {
"type": "string",
"minLength": 1,
"description": "Free-text natural-language query, or a 17-character VIN for exact listing lookup. For sentences (e.g. \"new black Honda Civic sedan under $45k within 150 miles of 92672\"), price/mileage/year/condition and zip+radius are parsed as hard constraints; make/model/color/body words are matched forgivingly. Explicit structured params override parsed values. Prefer filter_vehicles when make/model/location are already known."
},
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude coordinate"
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude coordinate"
},
"zip": {
"type": "string",
"pattern": "^[0-9]{5}$",
"description": "5-digit US ZIP code (e.g., 92688)"
},
"city": {
"type": "string",
"minLength": 1,
"description": "City name"
},
"make": {
"type": "string",
"minLength": 1,
"description": "Vehicle make (e.g., Honda, Toyota, Tesla)"
},
"mode": {
"enum": [
"keyword",
"hybrid"
],
"type": "string",
"description": "Search mode. Use hybrid for conceptual queries with little keyword overlap (e.g. \"family hauler good in snow\"). Hard caps still apply as filters. Falls back to keyword if semantic is unavailable."
},
"near": {
"type": "string",
"minLength": 1,
"description": "Location string (ZIP or city, state). Same as GET /v1/vehicles/search near."
},
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number (1-based). Same as GET /v1/vehicles/search page."
},
"trim": {
"type": "string",
"minLength": 1,
"description": "Trim level (e.g., EX, Limited, Performance)"
},
"year": {
"type": "integer",
"maximum": 2100,
"minimum": 1900,
"description": "Alias for vehicleModelDate. Same as GET /v1/vehicles/search year."
},
"class": {
"enum": [
"side-by-side",
"atv",
"snowmobile"
],
"type": "string",
"description": "Off-road class. Legal when vertical=offroad. side-by-side, atv, or snowmobile."
},
"color": {
"type": "string",
"minLength": 1,
"description": "Exterior color (e.g., black, white). Resolved to color families, so \"black\" matches \"Crystal Black Pearl\". Same as GET /v1/vehicles color."
},
"drive": {
"enum": [
"2wd",
"4wd",
"awd"
],
"type": "string",
"description": "Drive: 2wd, 4wd, or awd. Legal when vertical=offroad. Same as GET /v2/listings/search drive."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of results to return (1-100, default: 25)"
},
"model": {
"type": "string",
"minLength": 1,
"description": "Vehicle model (e.g., Civic, Camry, Model 3). Broad terms match all variants (Civic -> Civic Sedan/Si/Hatchback) unless narrowed by trim."
},
"seats": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Seating capacity. Legal when vertical=offroad. Same as GET /v2/listings/search seats."
},
"state": {
"description": "2-letter US state code (e.g., CA, TX)"
},
"county": {
"type": "string",
"minLength": 1,
"description": "County name"
},
"radius": {
"type": "integer",
"maximum": 250,
"minimum": 1,
"description": "Search radius in miles (1-250). Omit to use the platform default of 150 miles, the same as the shop and the Runtime API."
},
"sortBy": {
"enum": [
"price",
"vehiclemodeldate",
"distance",
"updatedat",
"mileage",
"daysonlot",
"pricechange"
],
"type": "string",
"description": "Sort field. Same as GET /v1/vehicles/search sortBy: price, vehiclemodeldate, distance, updatedat, mileage, daysonlot, pricechange."
},
"subtype": {
"enum": [
"sport",
"utility",
"youth"
],
"type": "string",
"description": "Off-road sub-type: sport, utility, or youth. Legal when vertical=offroad. Same as GET /v2/listings/search subtype."
},
"yearMax": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Maximum model year. Same as GET /v1/vehicles yearMax."
},
"yearMin": {
"type": "integer",
"maximum": 2030,
"minimum": 1990,
"description": "Minimum model year. Same as GET /v1/vehicles yearMin."
},
"bodyType": {
"enum": [
"sedan",
"suv",
"truck",
"coupe",
"van",
"wagon",
"convertible",
"hatchback"
],
"type": "string",
"description": "Vehicle body style. Same as GET /v1/vehicles bodyType."
},
"dealerId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Filter to a single dealer UUID. Same as GET /v1/vehicles/search dealerId."
},
"fuelType": {
"enum": [
"gasoline",
"diesel",
"electric",
"hybrid",
"plug-in-hybrid"
],
"type": "string",
"description": "Fuel type. Same as GET /v1/vehicles fuelType."
},
"priceMax": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum price in USD. Same as GET /v1/vehicles priceMax."
},
"priceMin": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Minimum price in USD. Same as GET /v1/vehicles priceMin."
},
"vertical": {
"type": "string",
"minLength": 1,
"description": "Shopper vertical. Omit for every public vertical (cars today). Live verticals come from list_verticals."
},
"certified": {
"type": "boolean",
"description": "Certified pre-owned only. Same as GET /v1/vehicles certified."
},
"condition": {
"enum": [
"new",
"used",
"cpo"
],
"type": "string",
"description": "Listing condition. Same as GET /v1/vehicles condition: new, used, or cpo. The value certified is a deprecated alias of cpo."
},
"hasImages": {
"type": "boolean",
"description": "Listings with zero photos are omitted. Same as GET /v1/vehicles/search hasImages=true."
},
"sortOrder": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Sort direction. Same as GET /v1/vehicles sortOrder."
},
"drivetrain": {
"enum": [
"fwd",
"rwd",
"awd",
"4wd"
],
"type": "string",
"description": "Drivetrain configuration. Same as GET /v1/vehicles drivetrain."
},
"mileageMax": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum mileage. Same as GET /v1/vehicles mileageMax."
},
"transmission": {
"enum": [
"automatic",
"manual",
"cvt"
],
"type": "string",
"description": "Transmission type. Same as GET /v1/vehicles transmission."
},
"semanticRatio": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "Semantic blend weight 0..1 when mode=hybrid (default 0.5). Higher = more conceptual matching."
},
"priceChangeMax": {
"type": "number",
"description": "Maximum indexed priceChange (USD delta vs first recorded ask; use -1 to exclude unchanged listings)"
},
"priceChangeMin": {
"type": "number",
"description": "Minimum indexed priceChange (USD delta vs first recorded ask; negative means a drop)"
},
"displacementMax": {
"type": "number",
"minimum": 0,
"description": "Maximum engine displacement in cc. Legal when vertical=offroad. Same as GET /v2/listings/search displacementMax."
},
"displacementMin": {
"type": "number",
"minimum": 0,
"description": "Minimum engine displacement in cc. Legal when vertical=offroad. Same as GET /v2/listings/search displacementMin."
},
"inventoryStatus": {
"enum": [
"on_lot",
"in_transit",
"sold",
"reserved",
"all"
],
"type": "string",
"description": "Inventory disposition filter. Same as GET /v1/vehicles/search inventoryStatus."
},
"vehicleModelDate": {
"type": "integer",
"maximum": 2100,
"minimum": 1900,
"description": "Exact model year. Same as GET /v1/vehicles/search vehicleModelDate."
}
},
"additionalProperties": false
}