API Documentation
Complete reference for the Vehicle Finder API. All endpoints are under https://api.vehicle-finder.com/v1
On this page
Authentication
Pass your API key in the X-API-Key header with every request.
curl -H "X-API-Key: vda_your_key_here" \ https://api.vehicle-finder.com/v1/makes
Rate Limits
Rate limits are per-minute and per-month based on your plan. Every response carries these headers:
X-RateLimit-Limit— Requests per minuteX-RateLimit-Remaining— Remaining this minuteX-RateLimit-Reset— Unix timestamp (seconds) when the per-minute window resetsX-Monthly-Limit— Monthly quotaX-Monthly-Remaining— Remaining this month
Exceeding either limit returns 429 Too Many Requests with the error slug rate_limited and a Retry-After header holding the number of seconds to wait — until the next minute for the per-minute limit, or until the next billing month for the monthly quota.
HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1767225660
X-Monthly-Limit: 10000
X-Monthly-Remaining: 9210
{ "error": "rate_limited", "detail": "Rate limit exceeded. 60 requests per minute allowed." }Errors
Every error response uses the same JSON envelope. error is a stable slug you can branch on; detail is a human-readable message — or, for validation_error, a list of field errors.
{ "error": "not_found", "detail": "Vehicle not found" }
// validation_error — detail is a list
{
"error": "validation_error",
"detail": [
{ "loc": ["query", "year"], "msg": "Input should be a valid integer", "type": "int_parsing" }
]
}bad_request— 400 · Malformed request or unsupported parameter valueunauthorized— 401 · Missing, invalid, or inactive API keyforbidden— 403 · Endpoint not included in your plan, or email not confirmednot_found— 404 · No vehicle or data record matchedconflict— 409 · Request conflicts with existing statevalidation_error— 422 · A path or query parameter failed validationrate_limited— 429 · Per-minute or monthly limit exceeded (see Rate Limits)internal_error— 500 · Unexpected server error; the body also carries arequest_idto quote to support
Plans & Access
Each endpoint below carries a badge for the lowest plan that includes it. Higher plans include everything below them. Access is enforced: calling an endpoint above your plan returns 403 forbidden with the plan you need. See pricing for the full feature lists and request quotas.
- FreeLookup, VIN decoding, makes & models
- StarterSpecs, fluids, parts, maintenance, recalls
- ProDiagnostics, TSBs, complaints, towing, costs
Vehicles
/v1/makesFreeList all vehicle makes
/v1/makes/{make}/models?year=FreeList models for a make (optional year filter)
/v1/vehicles?year=&make=&model=FreeLook up a vehicle by year, make, and model
/v1/vehicles/{id}FreeGet a vehicle by ID
/v1/vehicles/batchFreeLook up several vehicles in one request — one entry per requested vehicle, returned in request order
/v1/vin/{vin}FreeDecode a 17-character VIN
// POST /v1/vehicles/batch — request
{
"vehicles": [
{ "year": 2024, "make": "Toyota", "model": "Camry" },
{ "year": 2023, "make": "Ford", "model": "F-150", "trim": "XLT" }
]
}
// Response — matches is empty (not an error) for a vehicle that isn't in the dataset
{
"data": [
{
"query": { "year": 2024, "make": "Toyota", "model": "Camry" },
"matches": [
{ "id": 4521, "year": 2024, "make": "Toyota", "model": "Camry", "trim": "LE", "engine": "2.5L I4" }
]
},
{
"query": { "year": 2023, "make": "Ford", "model": "F-150", "trim": "XLT" },
"matches": [
{ "id": 3104, "year": 2023, "make": "Ford", "model": "F-150", "trim": "XLT", "engine": "3.5L V6 EcoBoost" }
]
}
]
}// VIN Decode Response
{
"data": {
"year": 2024, "make": "Toyota", "model": "Camry", "trim": "SE",
"engine": "2.5L I4 DOHC 16V", "vehicle_id": 4521,
"body_class": "Sedan/Saloon", "doors": 4,
"drive_type": "FWD", "fuel_type": "Gasoline",
"displacement_liters": 2.5, "cylinders": 4, "engine_config": "In-Line",
"horsepower": 203.0, "transmission": "Automatic", "transmission_speeds": "8",
"plant_city": "GEORGETOWN", "plant_country": "United States (USA)",
"manufacturer": "Toyota Motor Manufacturing",
"vehicle_type": "PASSENGER CAR",
"gvwr": "Class 1C: 4,001 - 5,000 lb (1,814 - 2,268 kg)"
}
}Vehicle Summary
/v1/vehicles/{id}/summary?include=FreeSeveral data sections for one vehicle in a single call. include is a comma-separated list of oil, recalls, fuel-economy, reliability. Each section follows its own endpoint's plan — requesting a section above your plan returns 403
Use this instead of fanning out four requests when you render a vehicle detail page. Each requested section comes back under its own key and is null when that data isn't available for the vehicle — a missing section is never an error. Sections you don't include are omitted. The call counts as one request against your quota.
// GET /v1/vehicles/4521/summary?include=oil,recalls,fuel-economy,reliability
{
"data": {
"vehicle": { "id": 4521, "year": 2024, "make": "Toyota", "model": "Camry", "trim": "LE", "engine": "2.5L I4" },
"oil": {
"oil_spec": { "viscosity": "0W-16", "oil_type": "Full Synthetic", "capacity_with_filter": 4.8 },
"filters": [{ "brand": "Toyota", "part_number": "04152-YZZA1", "is_oem": true }],
"drain_bolt": { "socket_size_mm": 14, "torque_nm": 30 }
},
"recalls": [
{ "id": 88213, "nhtsa_campaign": "24V123000", "description": "...", "date_issued": "2024-03-14" }
],
"fuel-economy": [
{ "city_mpg": 28, "highway_mpg": 39, "combined_mpg": 32, "fuel_type": "Regular Gasoline" }
],
"reliability": null
}
}Oil Change
/v1/vehicles/{id}/oil-changeStarterOil specs, filters, and drain bolt info
// Response
{
"data": {
"oil_spec": {
"viscosity": "0W-20",
"oil_type": "Full Synthetic",
"capacity_with_filter": 5.0,
"capacity_without_filter": 4.6
},
"filters": [{ "brand": "Toyota", "part_number": "04152-YZZA1", "is_oem": true }],
"drain_bolt": { "socket_size_mm": 14, "torque_nm": 25 }
}
}Fluids
/v1/vehicles/{id}/fluidsStarterTransmission, brake, coolant, power steering, differential, and transfer case fluid specs
// Response
{
"data": {
"vehicle_id": 1,
"year": 2024, "make": "Toyota", "model": "Camry",
"transmission_fluid": { "fluid_type": "ATF WS", "capacity_quarts": 3.7 },
"brake_fluid": { "dot_type": "DOT 3" },
"coolant": { "coolant_type": "Long Life", "color": "Pink", "capacity_quarts": 6.4 },
"power_steering_fluid": { "fluid_type": "ATF Dexron III" },
"differential_fluids": [{ "position": "rear", "fluid_type": "75W-90" }],
"transfer_case_fluid": null
}
}Parts
/v1/vehicles/{id}/partsStarterSpark plugs, air filters, cabin filters, brake pads/rotors, wiper blades, battery, and tire specs
// Response
{
"data": {
"vehicle_id": 1,
"spark_plug_spec": { "plug_type": "Iridium", "gap": "0.044", "quantity": 4 },
"battery_spec": { "group_size": "35", "cca": 550 },
"tire_spec": { "size": "215/55R17", "pressure_front_psi": 35, "pressure_rear_psi": 35 },
"spark_plugs": [{ "brand": "NGK", "part_number": "ILKAR7B11", "is_oem": true }],
"air_filters": [{ "brand": "Toyota", "part_number": "17801-YZZ02", "is_oem": true }],
"brake_pads": [{ "brand": "Akebono", "part_number": "ACT1293", "position": "front" }],
"wiper_blades": [{ "brand": "Bosch", "part_number": "26A", "position": "driver", "size_inches": 26 }],
"batteries": [{ "brand": "Interstate", "part_number": "MTZ-35", "is_oem": false }]
}
}Maintenance
/v1/vehicles/{id}/maintenance?mileage=StarterMaintenance schedule (optional mileage filter)
Recalls
/v1/vehicles/{id}/recallsStarterNHTSA safety recalls
// Response
{
"data": [
{
"id": 88213,
"nhtsa_campaign": "24V123000",
"description": "The fuel pump may fail, causing an engine stall while driving.",
"consequence": "An engine stall increases the risk of a crash.",
"remedy": "Dealers will replace the fuel pump free of charge.",
"date_issued": "2024-03-14",
"source": "nhtsa"
}
]
}Diagnostics
/v1/diagnostics/{dtc_code}StarterLook up a DTC code (e.g., P0301)
/v1/vehicles/{id}/diagnostics/{code}ProVehicle-specific diagnostic with repair costs
Technical Service Bulletins
/v1/vehicles/{id}/tsbProTechnical Service Bulletins
Consumer Complaints
/v1/vehicles/{id}/complaints?component=&limit=&offset=ProNHTSA consumer complaints with crash, fire, and injury data
/v1/vehicles/{id}/common-problemsProTop reported problems aggregated by component
// Common Problems Response
{
"data": [
{
"component": "ENGINE",
"complaint_count": 47,
"crash_count": 2,
"fire_count": 1,
"injury_count": 3,
"death_count": 0,
"sample_description": "Engine stalls intermittently while driving..."
}
]
}Torque Specs
/v1/vehicles/{id}/torque-specsStarterLug nut, drain bolt, and spark plug torque specifications
// Response
{
"data": [
{ "component": "lug_nut", "torque_ft_lbs": 76, "torque_nm": 103.0, "notes": "Alloy wheels" },
{ "component": "drain_bolt", "torque_ft_lbs": 30, "torque_nm": 40.7, "notes": "Use new crush washer" },
{ "component": "spark_plug", "torque_ft_lbs": 18, "torque_nm": 24.4, "notes": "14mm thread, aluminum head" }
]
}Towing & Payload
/v1/vehicles/{id}/towingProTowing capacity, payload, curb weight, GVWR, and hitch class (trucks/SUVs)
// Response (2024 Ford F-150)
{
"data": {
"max_towing_lbs": 13000,
"max_payload_lbs": 3325,
"curb_weight_lbs": 4069,
"gvwr_lbs": 7050,
"tongue_weight_lbs": 1300,
"hitch_class": "IV"
}
}Service Cost Estimates
/v1/vehicles/{id}/service-costs?region=&service_type=ProEstimated repair costs by region with parts and labor breakdowns
Regions: national, northeast, southeast, midwest, southwest, west
// Response
{
"data": [
{
"service_type": "oil_change_synthetic",
"region": "west",
"cost_low": 90,
"cost_high": 190,
"cost_average": 140,
"labor_hours_low": 0.3,
"labor_hours_high": 0.5,
"parts_cost_low": 50,
"parts_cost_high": 120
}
]
}Fuel Economy
/v1/vehicles/{id}/fuel-economyStarterEPA fuel economy ratings — city, highway, combined MPG, annual fuel cost; MPGe and electric range for EVs and plug-in hybrids
/v1/fuel-economy?year=&make=&model=StarterSearch fuel economy by year/make/model (returns all trims and engines)
// Response
{
"data": [{
"year": 2024, "make": "Toyota", "model": "Camry",
"city_mpg": 28, "highway_mpg": 39, "combined_mpg": 32,
"annual_fuel_cost": 1750,
"engine_displacement": 2.5, "cylinders": 4,
"transmission": "Automatic (S8)", "drive": "FWD",
"fuel_type": "Regular Gasoline", "vehicle_class": "Midsize Cars",
"city_mpge": null, "highway_mpge": null, "combined_mpge": null,
"electric_range": null
}]
}
// EVs and plug-in hybrids populate the MPGe fields and electric_range (miles)
{
"data": [{
"year": 2024, "make": "Tesla", "model": "Model 3",
"city_mpg": null, "highway_mpg": null, "combined_mpg": null,
"city_mpge": 138, "highway_mpge": 126, "combined_mpge": 132,
"electric_range": 272, "annual_fuel_cost": 550,
"transmission": "Automatic (A1)", "drive": "RWD",
"fuel_type": "Electricity", "vehicle_class": "Midsize Cars"
}]
}Engine Specs
/v1/vehicles/{id}/engine-specsStarterDetailed engine specifications — horsepower, torque, displacement, aspiration, valve config, and engine internals
// Response (2024 Ford F-150)
{
"data": [
{
"engine_variant": "3.5L EcoBoost V6",
"horsepower": 400, "horsepower_rpm": 6000,
"torque_ft_lbs": 500, "torque_rpm": 3100,
"displacement_liters": 3.5, "displacement_cc": 3496,
"cylinders": 6, "cylinder_config": "V",
"valve_count": 24, "valve_config": "DOHC",
"fuel_system": "Direct Injection",
"aspiration": "Twin-Turbo",
"compression_ratio": "10.0:1",
"engine_code": "Duratec",
"block_material": "Aluminum", "head_material": "Aluminum"
},
{
"engine_variant": "5.0L Coyote V8",
"horsepower": 400, "horsepower_rpm": 6000,
"torque_ft_lbs": 410, "torque_rpm": 4250,
"displacement_liters": 5.0, "displacement_cc": 4951,
"cylinders": 8, "cylinder_config": "V",
"aspiration": "Naturally Aspirated"
}
]
}Transmission Spec
/v1/vehicles/{id}/transmission-specStarterTransmission model code, type (CVT/Auto/Manual/DCT), gear count, fluid capacity, and max input torque
// Response (2024 Ford F-150)
{
"data": {
"model_code": "10R80",
"transmission_type": "Automatic",
"speeds": 10,
"manufacturer": "Ford",
"fluid_capacity_quarts": 13.1,
"max_input_torque_ft_lbs": 590,
"notes": null,
"source": "manufacturer"
}
}Forced Induction
/v1/vehicles/{id}/forced-inductionStarterTurbo/supercharger details — induction type, turbo model, intercooler, max boost, wastegate, and service interval. Returns 404 (not_found) for naturally aspirated engines
// Response (2024 Ford F-150 3.5L EcoBoost)
{
"data": {
"induction_type": "Twin-Turbo",
"turbo_model": "Garrett GT1549",
"intercooler_type": "Air-to-Air",
"max_boost_psi": 18.0,
"wastegate_type": "Electronic",
"service_interval_miles": 100000,
"notes": null,
"source": "manufacturer"
}
}Safety Ratings
/v1/vehicles/{id}/safety-ratingsProNHTSA crash test safety ratings — overall, frontal, side, and rollover scores (1-5 stars)
// Response
{
"data": {
"overall_rating": 5,
"frontal_crash_driver": 4,
"frontal_crash_passenger": 5,
"side_crash_driver": 5,
"side_crash_passenger": 5,
"rollover_rating": 4,
"rollover_risk_pct": 12.6,
"side_pole_rating": 5
}
}Warranty
/v1/vehicles/{id}/warrantyProManufacturer warranty coverage — basic, powertrain, corrosion, roadside, and battery warranties
// Response
{
"data": [
{ "warranty_type": "basic", "months": 36, "miles": 36000, "notes": "Bumper-to-bumper" },
{ "warranty_type": "powertrain", "months": 60, "miles": 60000, "notes": "Engine, transmission, drivetrain" },
{ "warranty_type": "corrosion", "months": 60, "miles": null, "notes": "Body rust-through" },
{ "warranty_type": "roadside", "months": 24, "miles": 25000, "notes": "24/7 roadside assistance" }
]
}Maintenance Predictor
/v1/vehicles/{id}/maintenance/predict?mileage=45000StarterPredict overdue, due now, and upcoming maintenance based on current mileage
// Response
{
"data": {
"vehicle_id": 4521,
"current_mileage": 45000,
"overdue": [],
"due_now": [
{ "description": "Replace engine air filter", "mileage_interval": 45000,
"status": "due_now", "due_at_miles": 45000, "miles_until_due": 0 }
],
"upcoming": [
{ "description": "Replace spark plugs", "mileage_interval": 60000,
"status": "upcoming", "due_at_miles": 60000, "miles_until_due": 15000 }
]
}
}Total Cost of Ownership
/v1/vehicles/{id}/tco?annual_miles=12000&gas_price=3.50Pro5-year cost projection combining fuel, maintenance, depreciation, and insurance
// Response
{
"data": {
"vehicle_id": 4521,
"year": 2024, "make": "Toyota", "model": "Camry",
"annual_miles": 12000, "gas_price": 3.5,
"breakdown": {
"fuel_annual": 1312, "fuel_5yr": 6562,
"maintenance_annual": 680, "maintenance_5yr": 3400,
"depreciation_5yr": 8500,
"insurance_annual_est": 1200, "insurance_5yr_est": 6000,
"total_annual": 4892, "total_5yr": 24462
}
}
}Towing Calculator
/v1/vehicles/{id}/towing/calculator?cargo_weight=5000&passengers=2ProCheck if a vehicle can tow a given weight with safety warnings
// Response
{
"data": {
"max_towing_lbs": 13000,
"max_payload_lbs": 3325,
"cargo_weight": 5000,
"tongue_weight_est": 600,
"remaining_towing_capacity": 8000,
"remaining_payload": 2425,
"can_tow": true,
"can_carry": true,
"warnings": []
}
}Similar Vehicles
/v1/vehicles/{id}/similar?year_range=2&limit=5StarterFind comparable vehicles by year, price, and class
// Response
{
"data": [
{ "vehicle_id": 5102, "year": 2024, "make": "Honda", "model": "Accord",
"msrp": 28500, "combined_mpg": 33 },
{ "vehicle_id": 5305, "year": 2024, "make": "Hyundai", "model": "Sonata",
"msrp": 27500, "combined_mpg": 32 }
]
}Emissions
/v1/vehicles/{id}/emissionsStarterCO2 emissions per mile and per year, smog and greenhouse gas ratings
// Response
{
"data": {
"vehicle_id": 4521,
"co2_grams_per_mile": 277.7,
"co2_tons_per_year": 3.33,
"smog_rating": 7,
"greenhouse_rating": 7,
"fuel_type": "Regular Gasoline",
"combined_mpg": 32.0,
"is_zero_emission": false
}
}Vehicle Images
/v1/vehicles/{id}/images?angle=front&color=whiteStarterVehicle photos filtered by angle (front, rear, side, interior) and color
// Response
{
"data": [
{
"url": "https://example.com/2024-camry-front-white.jpg",
"angle": "front",
"color": "Super White",
"width": 1920,
"height": 1080,
"source": "manufacturer",
"license_type": "editorial"
}
]
}Reliability Scores
/v1/vehicles/{id}/reliabilityStarterReliability score (0-100) based on NHTSA complaint data with severity breakdown
// Response
{
"data": {
"overall_score": 72.3,
"rating": "Good",
"complaint_count": 245,
"crash_count": 12,
"fire_count": 3,
"injury_count": 8,
"death_count": 0,
"severity_score": 418.0,
"top_issue": "ENGINE"
}
}Vehicle Valuation
/v1/vehicles/{id}/valuationProEstimated vehicle values — trade-in, private party, and retail — with MSRP and depreciation
// Response
{
"data": {
"msrp": 30000,
"trade_in_low": 14025,
"trade_in_high": 15675,
"private_party_low": 15675,
"private_party_high": 17325,
"retail_low": 18150,
"retail_high": 20625,
"depreciation_pct": 46.0,
"condition_notes": "Estimated values assume average condition and mileage for vehicle age."
}
}Paint Codes
/v1/vehicles/{id}/paint-codesStarterOEM paint codes, color names, color groups, types, hex values, and touch-up part numbers
// Response
{
"data": [
{
"color_name": "Super White",
"paint_code": "040",
"color_group": "White",
"paint_type": "Solid",
"hex_color": "#FFFFFF",
"touch_up_part_number": null
},
{
"color_name": "Midnight Black Metallic",
"paint_code": "218",
"color_group": "Black",
"paint_type": "Metallic",
"hex_color": "#0D0D0D",
"touch_up_part_number": null
}
]
}Data Changes
/v1/changes?since=&limit=StarterPoll for vehicles whose data changed since a cursor, grouped by data domain (vehicle, oil, fluids, parts, maintenance, safety, specs, diagnostics, costs, reliability, other) — keep local caches in sync without blind re-fetching
Start with since=0, store the returned next_cursor, and pass it as since on the next poll. Keep polling while has_more is true. limit (default 1000, max 10000) caps the change-log rows scanned per call; rows compact to one entry per vehicle. If full_resync_recommended is true your cursor predates the retained change history — re-fetch everything you cache, then resume from next_cursor.
// Response
{
"data": {
"changes": [
{ "vehicle_id": 4521, "domains": ["oil", "specs"], "vehicle_deleted": false,
"last_changed_at": "2026-08-30T14:12:09Z" },
{ "vehicle_id": 5102, "domains": ["vehicle"], "vehicle_deleted": true,
"last_changed_at": "2026-08-30T14:20:41Z" }
],
"next_cursor": 18234,
"has_more": false,
"full_resync_recommended": false
}
}Account & API Keys
These are the endpoints behind the dashboard. Write operations authenticate with your dashboard login session (cookie) rather than an API key, so a leaked key can never mint or rotate other keys. The read-only endpoints accept either.
/v1/account/keysFreeList your API keys with prefix, status, last use, and requests_30d (requests in the trailing 30 days)
/v1/account/keys?name=FreeCreate a key. The full secret is returned once — store it immediately
/v1/account/keys/{key_id}/rotateFreeRotate a key: issues a replacement with the same name and revokes the old one in the same call
/v1/account/keys/{key_id}FreeRevoke a key. Takes effect immediately and cannot be undone
/v1/account/usage?period=currentFreeRequests used, monthly limit, and remaining quota for the billing period
Rotation is the safe way to retire a key you suspect has leaked: the old key stops authenticating the moment the call returns, so deploy the new secret to every integration right away. Rotating never changes your quota — limits are per account, not per key.
// POST /v1/account/keys/1234/rotate
{
"data": {
"id": 1291,
"key": "vda_4f9c...e21b", // shown once — save it now
"prefix": "vda_4f9c8a1e",
"name": "Production",
"revoked_key_id": 1234,
"message": "Key rotated. The previous key has been revoked and will no longer authenticate."
}
}Code Examples
Python
import requests
headers = {"X-API-Key": "vda_your_key_here"}
r = requests.get(
"https://api.vehicle-finder.com/v1/vehicles",
params={"year": 2024, "make": "Toyota", "model": "Camry"},
headers=headers,
)
vehicle = r.json()["data"][0] # /vehicles returns a list of matchesJavaScript
const res = await fetch(
"https://api.vehicle-finder.com/v1/vehicles?year=2024&make=Toyota&model=Camry",
{ headers: { "X-API-Key": "vda_your_key_here" } }
);
const { data } = await res.json();