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.

Authentication

All requests require a Bearer token. Create one in your dashboard under API Tokens. Tokens are read-only.

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). The month follows your account's renewal date: on a paid plan the quota resets on the day your subscription renews, and restarts when you upgrade; on Free it resets on the day of the month you signed up. Paid plans also have a daily limit of 10% of the monthly quota (resets 00:00 UTC), and no self-serve plan may receive more than a quarter of one dataset (cars, motorcycles, boats or tire sizes) in 30 days; bulk access is a data licence. Successful responses include quota headers:

• X-RateLimit-Quota — your monthly call quota
• X-RateLimit-Used — calls used this month
• X-Data-Quota — your monthly records quota
• X-Data-Used — records served this month
• X-RateLimit-Daily-Quota / X-RateLimit-Daily-Used — calls today (paid plans)
• X-Data-Daily-Quota / X-Data-Daily-Used — records today (paid plans)

On the Free plan the /{type}/models taxonomy endpoints return model names only (limited: true); year ranges and record counts need Pro or higher.

Errors

• 401 — missing or invalid token
• 403 — your plan does not include API access
• 404 — no resource with that UUID
• 422 — validation error (e.g. no filter, or page over the cap); a query that does not narrow the dataset gets a working example request back
• 429 — a limit was reached: the per-minute rate, a monthly or daily quota, the 30-day share of a dataset, or a temporary pause for an unusually broad sweep. Every 429 carries a Retry-After header; quota refusals also have a stable code (monthly_quota_exceeded, monthly_records_exceeded, daily_quota_exceeded, daily_records_exceeded, dataset_limit_reached, api_suspended) and resets_at. Failed and refused calls never count against your quota.

Check names first

make and model filter on the catalogue's names, and the catalogue is US-market data that spells some names its own way: boat makes are company names such as Sea Ray Boats and Bayliner Marine Corp, and vehicles never sold in the US are not listed. Before a batch of lookups, read the names the catalogue uses and send those:

1. GET /{type}/makes: every make, as the catalogue spells it.
2. GET /{type}/models?make=…: that make's models (names only on the Free plan).
3. Or GET /resolve?q=…: a car or motorcycle as typed ("2019 chevy silverado 1500") in the catalogue's spelling.

Common spellings are read for you (chevy, F150, Model S, 3 Series). When the catalogue has no make or model by that name under any spelling, the empty list adds suggestions: the closest catalogue names to retry with. An empty list without suggestions means the name is right and your other filters (year, specs) match no record.

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 depends on your plan (10 on Free, 25 on Pro/Developer, 100 on Enterprise); a larger per_page is clamped to it and the X-Per-Page-Limit header says so. Depth is capped at 40 pages.

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.

Recalls by VIN

GET https://api.vehdb.com/v1/vin/{vin}/recalls

Decodes the VIN with NHTSA vPIC and returns the NHTSA recall campaigns issued for that make, model and year: vehicle (make, model, year, trim, engine, plant), matched_models, recalls with the manufacturer campaign number, the build window when NHTSA has one and hints where a campaign mentions the decoded engine, drivetrain or plant, plus open_investigations and safety_rating.

This is not a per-VIN repair check. NHTSA publishes no per-VIN recall data, so every response says match_level: "make_model_year" and repair_status: null and carries a disclaimer; show it to your users and send them to check_url (nhtsa.gov/recalls) or a dealer. A malformed or undecodable VIN is a 422, an NHTSA outage a 503 (retry); an empty recalls list only ever means no campaigns on record. Each campaign and investigation counts one row. Also available as the recalls_for_vehicle MCP tool with a vin argument.

Boat HIN decode and history

GET https://api.vehdb.com/v1/hin/{hin}

Decodes a Hull Identification Number (12 characters, or 14 with a country prefix such as US-): the builder from its U.S. Coast Guard manufacturer code, the serial, the build month and model year, and the builder's USCG recall campaigns. history adds what federal records hold on the hull: accidents (recreational boating accidents reported under the HIN, 1995-2023, newest 20) with accident_count, documentation (its record in the Coast Guard's monthly file of federally documented vessels, with the changes seen month to month; null until that file is loaded) and coverage.

No record found is not a clean record: only accidents above the reporting threshold reach the Coast Guard, several states released no records or no HINs (coverage.accidents.gaps), and only about 2% of boats are federally documented. Nothing here is a title, salvage or theft check. Counts one row plus one per recall, accident, documentation record and change. Also available as the decode_hin MCP tool with include_history: true.

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 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.

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 and usage, plus limits: every limit that applies to you (monthly and daily calls and records, widget views, each dataset's 30-day share) with used, remaining and, for fixed windows, resets_at. 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.