API Documentation
A read-only REST API over the VehDB vehicle database — cars, motorcycles, power boats and tire sizes. JSON responses, UUID-addressable resources, and the same token works for the MCP server.
Full API reference — interactive Every endpoint, parameter and response schema, grouped by dataset, with runnable example requests. Generated live from the OpenAPI spec.https://api.vehdb.com/v1
Authentication
All requests require a Bearer token. Create one in your dashboard under API Tokens. Tokens are read-only.
-H "Authorization: Bearer YOUR_API_TOKEN"
Rate limits & quota
Each plan has a per-minute rate limit, a monthly request quota and a monthly records quota (shared across the REST API and MCP). Successful responses include quota headers:
X-RateLimit-Quota— your monthly call quotaX-RateLimit-Used— calls used this monthX-Data-Quota— your monthly records quotaX-Data-Used— records served this month
| Plan | Rate | Monthly calls | Monthly records |
|---|---|---|---|
| Free | 10/min | 100 | 1,000 |
| Pro | 60/min | 1,000 | 25,000 |
| Developer | 300/min | 100,000 | 100,000 |
| Enterprise | 600/min | 250,000+ | 1,000,000+ |
The /{type}/models taxonomy endpoints require the Pro plan or higher; free plans filter records by make/model on the list endpoints.
Errors
401— missing or invalid token403— your plan does not include API access404— no resource with that UUID422— validation error (e.g. no filter, or page/per_page over the cap)429— monthly quota exceeded or rate limit hit
Search vehicles
GET https://api.vehdb.com/v1/{type} — type: cars · motorcycles · boats · tire-sizes
At least one filter is required (no full-table dumps). Page size is capped at 25 and depth at 40 pages.
make | exact manufacturer |
model | exact model |
year | exact year |
year_min / year_max | year range |
q | free-text over make/model |
per_page | 1–10 (default 10) |
page | 1–40 |
Get a vehicle
GET https://api.vehdb.com/v1/{type}/{uuid}
Returns the full record for a single vehicle. Internal IDs and timestamps are never exposed.
Tires for a car
GET https://api.vehdb.com/v1/cars/{uuid}/tire-sizes
OEM and alternate tire sizes that fit a car, matched by make/model and preferring the exact model year.
Owner complaints
GET https://api.vehdb.com/v1/cars/{uuid}/complaints
NHTSA ODI owner-complaint statistics for the car's make, model and year. Returns complaints.total with crashes, fires, injured and deaths; by_component (most reported first); by_received_year (when owners complained); and model_years (the five years either side, so a bad year stands out). Aggregated weekly from the full NHTSA complaint file — counts only, no narratives.
Each complaint counts once in the totals and once per component it names. Complaints are filed by owners and are not verified defects; they tend to precede recalls, so read this next to /recalls.
Crash record & EPA tests
GET https://api.vehdb.com/v1/cars/{uuid}/crashes
Two NHTSA datasets, kept apart in the response. fars is a census of fatal crashes: exact vehicles of this model year involved since 2020 and occupant deaths in them. crss is a weighted sample of police-reported crashes of every severity since 2016: national estimate and raw sample per severity, plus estimated_injury_crashes. Read fatal figures from fars only. Both are counts, not rates.
GET https://api.vehdb.com/v1/cars/{uuid}/epa-tests
EPA dynamometer test configurations for the car's model year and model: horsepower (manufacturer rated), test_weight_lb, axle_ratio, gears, and the raw fe_city / fe_highway results. Cars also carry smog_rating (1–10) and smartway from the EPA Green Vehicle Guide.
GET https://api.vehdb.com/v1/tire-sizes/plants/{code}
Decodes the plant code after DOT on a tire sidewall to the plant, city and country (NHTSA vPIC). Tire geometry responses now also return the service block: load index in kg/lb and speed symbol in km/h and mph.
Insights & scorecard
Aggregate views over every dataset, for analyst and agent questions that would otherwise take a sweep. Group counts and averages only; each row served meters against your row budget like a record.
GET https://api.vehdb.com/v1/insights/scorecard?make=Honda&model=Accord
The model-year scorecard: every model year of one make/model with trims and EPA mpg, NHTSA complaints and a complaint_percentile against all vehicles of the same model year (98 = only 2% drew more), crash and fire share, top component, recall campaigns and do_not_drive, open investigations, ncap_overall, FARS fatal-crash involvement, plus best, worst and per-year flags.
/insights/complaints/vehicles?year=2018 — most complained-about vehicles of a model year.
/insights/complaints/components?make=Ford — a brand's most reported components and their share of its complaints.
/insights/fatal-crashes/vehicles?year=2024 and /body-classes — FARS involvement by model and occupant deaths per involved vehicle by body class.
/insights/engines — displacement, cylinders and turbo share per model year.
/insights/fuel-economy/canada?by=vehicle_class — NRCan L/100 km, CO₂ and electrified share.
/insights/recalls/age — how many years after a model year its recalls arrive.
/insights/tires/rim-sizes — average OEM rim diameter per model year.
Plus the existing /insights/recalls/brands, /insights/fuel-economy and /insights/ev-share. AI agents get the same through the model_year_scorecard and vehicle_insights MCP tools.
Your lists
GET https://api.vehdb.com/v1/lists
The authenticated user's saved vehicles — the same collection curated in the dashboard. The heart of the platform: build it once, read it anywhere.
Account & quota
GET https://api.vehdb.com/v1/me
Returns your plan, rate limit, monthly quota and usage — handy for self-throttling.
MCP server
Prefer to drive this from an AI agent? The same data and token power our MCP server at https://mcp.vehdb.com/mcp — tools: search_vehicles, get_vehicle, tire_sizes_for_vehicle, my_lists.