# OpenDealer Runtime API

> Machine discovery for `https://api.opendealer.app` (OpenAPI 2.3.0). Remote MCP at `https://mcp.opendealer.app` (registry 2.3.0). Consumer marketplace HTML lives on `https://opendealer.shop`.

## Canonical links

- OpenAPI JSON: https://api.opendealer.app/openapi.json
- OpenAPI YAML: https://api.opendealer.app/openapi.yaml
- Interactive docs: https://api.opendealer.app/docs
- Auth (Auth.md): https://api.opendealer.app/auth.md
- RFC 9727 catalog: https://api.opendealer.app/.well-known/api-catalog
- MCP server card: https://api.opendealer.app/.well-known/mcp
- MCP registry JSON: https://mcp.opendealer.app/.well-known/mcp.json

## Citation rules

- Cite only each vehicle's canonical shop `url` + `vin`. Never cite `detailsUrl`.
- Never send shoppers to `/llm/*` HTML or `/v1/llm/*` as the human listing URL.
- `listingId` is `{dealer}:{identifier}` (percent-encode `:` in paths). The identifier is a VIN, a 12-character HIN, or an internal id.

## How to call it

Use `/v2`. Omit `vertical` to search every public vertical. Name `vertical` to search one live vertical, including one that is not public yet.

`/v1` is the frozen car API. It is the `/v2` handler with cars pinned. `Deprecation` and `Link` headers are sent on `/v1` only when a second vertical is public. There is no Sunset header.

## Public routes (generated from route registry)

### feeds

- `GET /feeds/index.json` — Feed discovery index
- `GET /feeds/inventory.json` — Paginated JSON inventory feed
- `GET /feeds/inventory.ndjson` — NDJSON inventory feed
- `GET /feeds/inventory.jsonld.ndjson` — Schema.org JSON-LD inventory feed
- `GET /feeds/openai-products.jsonl` — OpenAI product feed
- `GET /feeds/changes.ndjson` — Inventory change feed
- `GET /feeds/dealers.json` — Dealer directory feed
- `GET /feeds/facets.json` — Facet feed
- `GET /feeds/google-merchant.xml` — Google Merchant Center feed
- `GET /feeds/dealer/{slug}.ndjson` — Per-dealer NDJSON inventory feed

### ucp

- `GET /ucp/v1/products` — UCP product browse
- `GET /ucp/v1/products/search` — UCP product search
- `GET /ucp/v1/products/{id}` — UCP product by listingId or VIN
- `GET /ucp/v1/categories` — UCP product categories
- `GET /ucp/v1/categories/makes` — UCP makes category

### verticals

- `GET /v2/verticals` — List live verticals → MCP `list_verticals`

### dealers

- `GET /v2/dealers` — List dealers → MCP `dealers_near`
- `GET /v2/dealers/{dealerId}` — Dealer profile for the whole rooftop
- `GET /v2/dealers/{dealerId}/knowledge` — Dealer knowledge for the whole rooftop → MCP `get_dealer`
- `GET /v2/dealers/{dealerId}/inventory` — Dealer inventory across public verticals → MCP `dealer_inventory`

### listings

- `GET /v2/listings` — Structured listing search → MCP `filter_vehicles`
- `GET /v2/listings/search` — Natural language listing search → MCP `search_vehicles`
- `GET /v2/listings/facets` — Listing facets → MCP `list_facets`
- `GET /v2/listings/compare` — Compare listings in one vertical → MCP `compare_vehicles`
- `GET /v2/listings/{listingId}` — One rooftop unit → MCP `get_vehicle`
- `GET /v2/listings/{listingId}/history` — Listing price history → MCP `get_vehicle_history`
- `GET /v2/listings/{listingId}/similar` — Similar units in the same vertical → MCP `get_similar_vehicles`
- `GET /v2/listings/{listingId}/insights` — Deal score for a listing → MCP `get_deal_score`
- `GET /v2/listings/{listingId}/recalls` — Open recalls for a listing → MCP `check_recalls`

### vehicles

- `GET /v2/listings/dealer-summary` — Per-dealer totals for a filter scope

### market

- `GET /v2/market/overview` — Market overview → MCP `get_market_overview`
- `GET /v2/market/segments` — Browse market segments → MCP `list_market_segments`
- `GET /v2/market/segments/{modelcode}` — Market segment detail → MCP `get_market_segment`
- `GET /v2/market/trends` — Market price trends → MCP `get_market_trends`
- `GET /v2/market/compare` — Compare market segments → MCP `compare_market`
- `GET /v2/market/velocity` — Market velocity → MCP `get_market_velocity`

### research

- `GET /v2/research/makes` — Research makes catalog → MCP `list_research_makes`
- `GET /v2/research/makes/{make}` — Models for a make → MCP `list_research_models`
- `GET /v2/research/models/{make}/{model}` — Model research payload → MCP `research_model`
- `GET /v2/research/models/{make}/{model}/safety` — NHTSA safety ratings for YMM → MCP `get_safety_rating`
- `GET /v2/research/compare` — Compare 2-4 models → MCP `compare_models`
- `GET /v2/research/rankings` — Vehicle ranking categories → MCP `get_vehicle_rankings`
- `GET /v2/research/rankings/{category}` — Rankings for a category
- `GET /v2/research/rankings/{category}/inventory` — Live listing counts for a ranking category
- `GET /v2/research/sitemap` — Research make/model sitemap pairs

### sitemap-data

- `GET /v2/sitemap/makes` — Makes for sitemap generation
- `GET /v2/sitemap/models` — Make/model pairs for sitemaps
- `GET /v2/sitemap/years` — Model years for sitemaps
- `GET /v2/sitemap/dealers/count` — Dealer count
- `GET /v2/sitemap/dealers` — Dealer slugs for sitemaps
- `GET /v2/sitemap/zipcodes` — ZIP codes for geo sitemaps
- `GET /v2/sitemap/trims` — Trims for sitemaps
- `GET /v2/sitemap/cities` — Cities for geo sitemaps
- `GET /v2/sitemap/make-model-cities` — Make/model by city for sitemaps
- `GET /v2/sitemap/make-model-year-cities` — Make/model/year by city for sitemaps
- `GET /v2/sitemap/vehicles/count` — Vehicle count for sitemap shards
- `GET /v2/sitemap/vehicles` — Vehicle rows for sitemaps

### places

- `GET /v2/places/city-state/{slug}` — Resolve a city-state slug
- `GET /v2/places/zip/{zip}` — Resolve a ZIP code

### finance

- `GET /v2/finance/suggested-rates` — Suggested auto loan APRs → MCP `get_suggested_rates`

## Deprecated routes (use successors)

These paths remain available for backward compatibility. Prefer the successor for new integrations.

- `GET /v1/verticals` — deprecated; use `/v2/verticals` — List live verticals
- `GET /v1/dealers` — deprecated; use `/v2/dealers` — List dealers by location or name
  - Example: `/v1/dealers?city=Dallas&state=TX&radius=150&limit=20`
- `GET /v1/dealers/{dealerId}` — deprecated; use `/v2/dealers/{dealerId}` — Dealer profile
- `GET /v1/dealers/{dealerId}/knowledge` — deprecated; use `/v2/dealers/{dealerId}/knowledge` — Dealer knowledge for AI assistants
- `GET /v1/dealers/{dealerId}/inventory` — deprecated; use `/v2/dealers/{dealerId}/inventory` — Dealer inventory
  - Example: `/v1/dealers/rancho-santa-margarita-honda/inventory?limit=25`
- `GET /v1/vehicles` — deprecated; use `/v2/listings` — Structured vehicle search
  - Example: `/v1/vehicles?zip=92688&radius=50&make=Honda&limit=25`
  - Example: `/v1/vehicles?make=Ford&city=Tulsa&state=OK&limit=25`
- `GET /v1/vehicles/search` — deprecated; use `/v2/listings/search` — Meilisearch vehicle search
- `GET /v1/vehicles/facets` — deprecated; use `/v2/listings/facets` — Inventory facet values
- `GET /v1/vehicles/dealer-summary` — deprecated; use `/v2/listings/dealer-summary` — Per-dealer totals for a filter scope
- `GET /v1/vehicles/compare` — deprecated; use `/v2/listings/compare` — Compare 2-5 vehicles by VIN or listingId
- `GET /v1/vehicles/{vin}` — deprecated; use `/v2/listings/{listingId}` — Vehicle by VIN
- `GET /v1/listings/{listingId}` — deprecated; use `/v2/listings/{listingId}` — One rooftop listing by listingId
- `GET /v1/vehicles/{vin}/insights` — deprecated; use `/v2/listings/{listingId}/insights` — Deal score and market insights
- `GET /v1/vehicles/{vin}/history` — deprecated; use `/v2/listings/{listingId}/history` — Listing price history for a VIN
- `GET /v1/listings/{listingId}/history` — deprecated; use `/v2/listings/{listingId}/history` — Listing-scoped price history
- `GET /v1/vehicles/{vin}/similar` — deprecated; use `/v2/listings/{listingId}/similar` — Similar on-lot vehicles
- `GET /v1/vehicles/{vin}/recalls` — deprecated; use `/v2/listings/{listingId}/recalls` — NHTSA open recalls (YMM-granular)
- `GET /v1/llm` — deprecated; use `/v2/listings/search` — LLM search surface index
- `GET /v1/llm/filter` — deprecated; use `/v2/listings` — LLM filter segment guide
- `GET /v1/llm/filter/{segments}` — deprecated; use `/v2/listings` — Structured inventory filter (path segments)
- `GET /v1/llm/search` — deprecated; use `/v2/listings/search` — LLM natural-language search guide
- `GET /v1/llm/search/{query}` — deprecated; use `/v2/listings/search` — Natural-language inventory search
- `GET /v1/market/overview` — deprecated; use `/v2/market/overview` — Market overview
- `GET /v1/market/segments` — deprecated; use `/v2/market/segments` — Browse market segments
- `GET /v1/market/segments/{modelcode}` — deprecated; use `/v2/market/segments/{modelcode}` — Market segment detail
- `GET /v1/market/trends` — deprecated; use `/v2/market/trends` — Market price trends
- `GET /v1/market/compare` — deprecated; use `/v2/market/compare` — Compare market segments
- `GET /v1/market/velocity` — deprecated; use `/v2/market/velocity` — Market velocity
- `GET /v1/research/makes` — deprecated; use `/v2/research/makes` — Research makes catalog
- `GET /v1/research/makes/{make}` — deprecated; use `/v2/research/makes/{make}` — Models for a make
- `GET /v1/research/models/{make}/{model}` — deprecated; use `/v2/research/models/{make}/{model}` — Model research payload
- `GET /v1/research/models/{make}/{model}/safety` — deprecated; use `/v2/research/models/{make}/{model}/safety` — NHTSA safety ratings for YMM
- `GET /v1/research/compare` — deprecated; use `/v2/research/compare` — Compare 2-4 models
- `GET /v1/research/rankings` — deprecated; use `/v2/research/rankings` — Vehicle ranking categories
- `GET /v1/research/rankings/{category}` — deprecated; use `/v2/research/rankings/{category}` — Rankings for a category
- `GET /v1/research/rankings/{category}/inventory` — deprecated; use `/v2/research/rankings/{category}/inventory` — Live listing counts for a ranking category
- `GET /v1/research/sitemap` — deprecated; use `/v2/research/sitemap` — Research make/model sitemap pairs
- `GET /v1/sitemap/makes` — deprecated; use `/v2/sitemap/makes` — Makes for sitemap generation
- `GET /v1/sitemap/models` — deprecated; use `/v2/sitemap/models` — Make/model pairs for sitemaps
- `GET /v1/sitemap/years` — deprecated; use `/v2/sitemap/years` — Model years for sitemaps
- `GET /v1/sitemap/dealers/count` — deprecated; use `/v2/sitemap/dealers/count` — Dealer count
- `GET /v1/sitemap/dealers` — deprecated; use `/v2/sitemap/dealers` — Dealer slugs for sitemaps
- `GET /v1/sitemap/zipcodes` — deprecated; use `/v2/sitemap/zipcodes` — ZIP codes for geo sitemaps
- `GET /v1/sitemap/trims` — deprecated; use `/v2/sitemap/trims` — Trims for sitemaps
- `GET /v1/sitemap/cities` — deprecated; use `/v2/sitemap/cities` — Cities for geo sitemaps
- `GET /v1/sitemap/make-model-cities` — deprecated; use `/v2/sitemap/make-model-cities` — Make/model by city for sitemaps
- `GET /v1/sitemap/make-model-year-cities` — deprecated; use `/v2/sitemap/make-model-year-cities` — Make/model/year by city for sitemaps
- `GET /v1/sitemap/vehicles/count` — deprecated; use `/v2/sitemap/vehicles/count` — Vehicle count for sitemap shards
- `GET /v1/sitemap/vehicles` — deprecated; use `/v2/sitemap/vehicles` — Vehicle rows for sitemaps
- `GET /v1/places/city-state/{slug}` — deprecated; use `/v2/places/city-state/{slug}` — Resolve a city-state slug
- `GET /v1/places/zip/{zip}` — deprecated; use `/v2/places/zip/{zip}` — Resolve a ZIP code
- `GET /v1/finance/suggested-rates` — deprecated; use `/v2/finance/suggested-rates` — Suggested auto loan APRs

## MCP quick connect

- Streamable HTTP: `https://mcp.opendealer.app/rpc` (optional Bearer for higher limits)
- ChatGPT path: `https://mcp.opendealer.app/mcp`