{"openapi":"3.1.0","info":{"title":"VehDB API","version":"1.0.0","description":"Vehicle data API: cars, motorcycles, power boats and tire fitments, enriched with EPA fuel economy and NHTSA safety data. All endpoints require a Bearer token (create one in the dashboard). List endpoints must narrow the dataset: supply make, model or q, a spec filter, or a year window of 10 years or less (an open-ended bound such as year_min=1900 is rejected). Drill down with \/{type}\/makes then \/{type}\/models?make=. See \/changelog for API changes.","contact":{"email":"support@vehdb.com"},"termsOfService":"https:\/\/mcp.vehdb.com\/terms"},"servers":[{"url":"https:\/\/api.vehdb.com\/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API token from the VehDB dashboard (read-only ability api:read)."}}},"paths":{"\/me":{"get":{"summary":"Your plan & quota","description":"Returns plan, rate limit, monthly quota and usage for the authenticated token.","responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/cars":{"get":{"summary":"List cars","description":"Filterable, paginated car records including EPA enrichment fields (mpg_city, mpg_highway, mpg_combined, epa_range_miles, annual_fuel_cost, co2_gpm).","parameters":[{"name":"make","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by manufacturer (exact)."},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by model (exact)."},{"name":"year","in":"query","required":false,"schema":{"type":"integer"},"description":"Exact model year."},{"name":"year_min","in":"query","required":false,"schema":{"type":"integer"},"description":"Year range lower bound."},{"name":"year_max","in":"query","required":false,"schema":{"type":"integer"},"description":"Year range upper bound."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Free-text search."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page size (max 10)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number (max 40, so one query yields at most 400 records)."},{"name":"body","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by body type (exact), e.g. Sedan or SUV."},{"name":"fuel_type","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by fuel type name (exact), e.g. GASOLINE or BATTERY ELECTRIC VEHICLE (BEV)."},{"name":"drive_type","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by drivetrain (exact), e.g. FWD, RWD, AWD, 4WD."},{"name":"ev_only","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to 1 to return only electrified vehicles (BEV, PHEV, HEV)."}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/cars\/makes":{"get":{"summary":"Car make taxonomy","description":"Every car manufacturer with its record count \u2014 aggregate counts only.","responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/cars\/models":{"get":{"summary":"Car model taxonomy","description":"Models for one make with their year range, for drilling down to records.","parameters":[{"name":"make","in":"query","required":false,"schema":{"type":"string"},"description":"Vehicle make (required)."}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/cars\/body-types":{"get":{"summary":"Car body-type taxonomy","description":"Every body type with its record count \u2014 aggregate counts only.","responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/cars\/{uuid}":{"get":{"summary":"Get a car","description":"Single car record by uuid, including EPA enrichment fields.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/cars\/{uuid}\/tire-sizes":{"get":{"summary":"Tires that fit a car","description":"Cross-reference: OEM and alternate tire fitments matched by make\/model, preferring the exact model year.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/cars\/{uuid}\/recalls":{"get":{"summary":"Car recalls & safety rating","description":"Live NHTSA recall campaigns and NCAP crash-test ratings (overall, front, side, rollover). Source: U.S. DOT, cached 24h.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/motorcycles":{"get":{"summary":"List motorcycles","description":"Filterable, paginated motorcycle records. The dataset also covers ATVs, UTVs, snowmobiles, scooters and personal watercraft \u2014 use vehicle_type to separate them.","parameters":[{"name":"make","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by manufacturer (exact)."},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by model (exact)."},{"name":"year","in":"query","required":false,"schema":{"type":"integer"},"description":"Exact model year."},{"name":"year_min","in":"query","required":false,"schema":{"type":"integer"},"description":"Year range lower bound."},{"name":"year_max","in":"query","required":false,"schema":{"type":"integer"},"description":"Year range upper bound."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Free-text search."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page size (max 10)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number (max 40, so one query yields at most 400 records)."},{"name":"motorcycle_type","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by riding type (exact), e.g. Street Motorcycle, Off-road Motorcycle, Dual Sport Motorcycle, Scooter, ATV, UTV \/ SXS, Snowmobile, Personal Watercraft, Golf Cart."},{"name":"vehicle_type","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by broad vehicle class (exact), e.g. Motorcycle or ATV\/UTV."}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/motorcycles\/makes":{"get":{"summary":"Motorcycle make taxonomy","description":"Every manufacturer with its record count \u2014 aggregate counts only.","responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/motorcycles\/models":{"get":{"summary":"Motorcycle model taxonomy","description":"Models for one make with their year range, for drilling down to records.","parameters":[{"name":"make","in":"query","required":false,"schema":{"type":"string"},"description":"Make (required)."}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/motorcycles\/types":{"get":{"summary":"Motorcycle type taxonomy","description":"Every riding type with its vehicle class and record count \u2014 aggregate counts only.","responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/motorcycles\/{uuid}":{"get":{"summary":"Get a motorcycle","description":"Single motorcycle record by uuid.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/motorcycles\/{uuid}\/recalls":{"get":{"summary":"Motorcycle recalls","description":"Live NHTSA recall campaigns for a motorcycle. Empty list = no match found in NHTSA naming, not a guarantee.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/boats":{"get":{"summary":"List power boats","description":"Filterable, paginated power-boat records (length, beam, dry weight, engine count, hp, hull material, fuel type).","parameters":[{"name":"make","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by manufacturer (exact)."},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by model (exact)."},{"name":"year","in":"query","required":false,"schema":{"type":"integer"},"description":"Exact model year."},{"name":"year_min","in":"query","required":false,"schema":{"type":"integer"},"description":"Year range lower bound."},{"name":"year_max","in":"query","required":false,"schema":{"type":"integer"},"description":"Year range upper bound."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Free-text search."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page size (max 10)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number (max 40, so one query yields at most 400 records)."},{"name":"hull_type","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by hull material (exact), e.g. Fiberglass or Aluminum."},{"name":"fuel_type","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by fuel type (exact), e.g. Gas or Diesel."},{"name":"model_type","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by vessel category (exact), e.g. Center Console."},{"name":"hp_min","in":"query","required":false,"schema":{"type":"integer"},"description":"Horsepower lower bound."},{"name":"hp_max","in":"query","required":false,"schema":{"type":"integer"},"description":"Horsepower upper bound."},{"name":"length_min","in":"query","required":false,"schema":{"type":"number"},"description":"Vessel length lower bound (feet)."},{"name":"length_max","in":"query","required":false,"schema":{"type":"number"},"description":"Vessel length upper bound (feet)."}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/boats\/makes":{"get":{"summary":"Boat make taxonomy","description":"Every boat manufacturer with its vessel count \u2014 aggregate counts only.","responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/boats\/models":{"get":{"summary":"Boat model taxonomy","description":"Models for one make with their year range, for drilling down to records.","parameters":[{"name":"make","in":"query","required":false,"schema":{"type":"string"},"description":"Make (required)."}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/boats\/hull-types":{"get":{"summary":"Boat hull-type taxonomy","description":"Every hull type with its vessel count \u2014 aggregate counts only.","responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/boats\/{uuid}":{"get":{"summary":"Get a power boat","description":"Single power-boat record by uuid.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/tire-sizes":{"get":{"summary":"List tire fitments","description":"Filterable, paginated tire fitment records (vehicle \u2192 OEM + alternate sizes).","parameters":[{"name":"make","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by manufacturer (exact)."},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by model (exact)."},{"name":"year","in":"query","required":false,"schema":{"type":"integer"},"description":"Exact model year."},{"name":"year_min","in":"query","required":false,"schema":{"type":"integer"},"description":"Year range lower bound."},{"name":"year_max","in":"query","required":false,"schema":{"type":"integer"},"description":"Year range upper bound."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Free-text search."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page size (max 10)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number (max 40, so one query yields at most 400 records)."},{"name":"tire_size","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by OEM size (exact), e.g. 245\/40R18."}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/tire-sizes\/makes":{"get":{"summary":"Tire fitment make taxonomy","description":"Every vehicle make in the fitment dataset with its record count \u2014 aggregate counts only.","responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/tire-sizes\/models":{"get":{"summary":"Tire fitment model taxonomy","description":"Models for one make, for cascading vehicle selectors. Chains with \/tire-sizes\/makes.","parameters":[{"name":"make","in":"query","required":false,"schema":{"type":"string"},"description":"Vehicle make (required)."}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/tire-sizes\/{uuid}":{"get":{"summary":"Get a tire fitment","description":"Single tire fitment record by uuid.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/tire-sizes\/{uuid}\/geometry":{"get":{"summary":"Tire size geometry & fitment check","description":"Computed geometry for the OEM size (width, sidewall, overall diameter, revs\/mile) and each alternate size with its diameter delta vs OEM. Within \u00b13% is the generally accepted fitment window.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/vin\/{vin}":{"get":{"summary":"Decode a VIN","description":"Decodes a 17-character VIN via NHTSA vPIC (make, model, year, engine, body, plant \u2014 cached 24h) and cross-references it against VehDB records: matching car and tire-fitment uuids for follow-up spec, recall and geometry calls.","parameters":[{"name":"vin","in":"path","required":true,"schema":{"type":"string","minLength":17,"maxLength":17},"description":"17-character VIN (letters I, O, Q are never valid)."}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}},"\/lists":{"get":{"summary":"Your lists","description":"The authenticated user's curated vehicle list (same data as the dashboard lists and the my_lists MCP tool).","responses":{"200":{"description":"OK"},"401":{"description":"Missing\/invalid token"},"403":{"description":"Plan has no API access"},"429":{"description":"Rate limit or monthly quota exceeded"}}}}}}