Vehicle data API reference

Overview

The Vehicles.dev API is a paid, server-to-server HTTP API. Every machine operation lives under /v1/vehicles/ on https://api.vehicles.dev and returnsapplication/json. The 11 data lookups use GET; vehicle history reports start with an idempotent POST and continue through account-owned list, status, and result resources. There is exactly one API version and no version header — the path prefix is the contract.

It is deliberately not browser-callable. No CORS headers are served, cookie authentication is rejected, and a request carrying an Origin header is refused outright. Call it from your backend and keep your key there.

What the data actually is

The synchronous data endpoints are built on a continuously crawled US vehicle dataset, joined against public federal sources where those are authoritative. The separate vehicle-history workflow preserves the canonical JSON returned by its report provider and keeps that result scoped to the ordering account.

• 1,721,693normalized dealer listings across 1,719,030 distinct vehicles
• 4,686,766price and mileage observations, appended on every crawl pass, powering valuation and marketplace analysis
• 3.7%median absolute percentage error of the gradient-boosted asking-price model on holdout data
• NHTSA + EPAvPIC for factory specifications and VIN fallback decoding, the recalls API for safety campaigns, and fueleconomy.gov for ownership costs

Provenance is explicit rather than implied. Every successful body carries source, VIN-keyed lookups add origin ("store" when we served it from our own dataset, "vpic" when we decoded it live), and valuation responses echo the exact feature vector the model scored.

What it is not

Market value is an asking price derived from live dealer listings, not a realized transaction price. Depreciation curves are per make and model, not per trim or VIN. Recalls are matched at the year/make/model level, so a campaign listing does not by itself prove a specific VIN is affected, and no public source tells us whether this car was repaired. Specifications are VIN-pattern decodes, not per-car build records, so they carry no factory option codes. Photo galleries hold what the source published and gave us — compare galleryCount against photoCount before assuming a gallery is complete. Each endpoint below states its own coverage limits — read them before you build on the numbers.

Quickstart

From zero to a real, billable response in about a minute. The calls below are copy and paste ready.

1. 01

   Sign up

   Create an account. Every new workspace lands on the free Starter plan with 1,000 included calls per month across all eleven synchronous vehicle data endpoints, plus a one-time $10 credit balance for usage after that shared allowance.

   Create a free accountOpen the dashboard

2. 02

   Mint an API key

   Open the dashboard, find the API keys panel, name a key and select "Create API key". The secret is displayed exactly once and is never recoverable — copy it immediately. Keys are scoped to Vehicles.dev; a key minted for another product is rejected with 401 invalid_credential.

3. 03

   Log in

   Install the CLI and log in once. vehicles login saves your key to ~/.vehicles/credentials.json — the MCP server reads the same file, so a single login covers both. Prefer raw HTTP or a server SDK? Export VEHICLES_API_KEY instead; the Bearer examples throughout these docs use it.

   npm install -g vehicles-dev-cli
   vehicles login

4. 04

   Make your first call

   Decode a VIN. This is a real, billable call against production data — it draws from your Starter plan's included calls first. (Raw HTTP: GET /v1/vehicles/vin/{vin} with an Authorization: Bearer header, shown under every endpoint below.)

   vehicles decode 5TDDZRBHXNS221317

   {
     "origin": "store",
     "source": "carscrape",
     "vehicle": {
       "year": 2022,
       "make": "Toyota",
       "model": "Highlander",
       "trim": "Limited",
       "body_style": "SUV",
       "drivetrain": "AWD",
       "fuel": "Gasoline",
       "transmission": "Automatic",
       "cylinders": 6,
       "doors": 4
     },
     "vin": "5TDDZRBHXNS221317"
   }

5. 05

   Read the response

   Read the response. "origin": "store" means the VIN matched a row in our scraped store and was served without a live external round trip; it does not guarantee that every field was enriched by vPIC. "vpic" means we decoded it live against NHTSA. Null fields are omitted rather than emitted as null, so treat every key inside vehicle as optional. The response also carried an x-request-id header — keep it if you need to open a support ticket about this call.

Official SDKs

Use the official, typed server-side clients when you do not want to manage bearer headers, query serialization, problem documents, timeouts, or history-report polling yourself. Both SDKs cover all 11 synchronous endpoints and the complete durable history-report workflow.

The first releases are installed from immutable GitHub v0.1.1 tags. npm and PyPI publication are not enabled yet, so use the exact commands below rather than an unversioned registry package.

pnpm add "github:vehicles-dev/typescript-sdk#v0.1.1"

import { Vehicles } from "@vehicles-dev/sdk";

const vehicles = new Vehicles({
  apiKey: process.env.VEHICLES_API_KEY!
});

const decoded = await vehicles.decodeVin("1HGCM82633A004352");
console.log({
  year: decoded.vehicle["year"],
  make: decoded.vehicle["make"],
  model: decoded.vehicle["model"],
  trim: decoded.vehicle["trim"]
});

pip install "vehicles-dev @ git+https://github.com/vehicles-dev/python-sdk.git@v0.1.1"

import os

from vehicles_dev import Vehicles

with Vehicles(os.environ["VEHICLES_API_KEY"]) as vehicles:
    decoded = vehicles.decode_vin("1HGCM82633A004352")
    vehicle = decoded["vehicle"]
    print({field: vehicle.get(field) for field in ("year", "make", "model", "trim")})

Authentication

Every /v1 request must carry a product API key as an HTTP bearer credential. There is no other scheme: no query-string keys, no basic auth, no cookies.

Authorization: Bearer $VEHICLES_API_KEY

The scheme token is case-sensitive Bearer followed by exactly one space. bearer, a double space, or any other scheme is rejected as 401 invalid_credential.

Keys

• Mint and revoke keys in the dashboard. The plaintext secret is returned exactly once at creation and is never recoverable — we store only a hash and the last four characters.
• Vehicles keys are prefixed vdev_. Keys are product-scoped: presenting a key minted for another product returns 401 invalid_credential.
• Rotation is create-then-revoke. Create the replacement key, deploy it, then revoke the old one — revocation takes effect immediately.
• Rate limits and credit balances are enforced per account, not per key, so splitting traffic across several keys does not raise your throughput ceiling.

An unauthenticated request

Calling any endpoint without a key returns a problem document. Note the x-request-id header, which is present on every response the API sends, successful or not.

HTTP/2 401
content-type: application/problem+json; charset=utf-8
x-request-id: 1f9fcd64-c8b4-4d8f-98b1-3b7ed12cae38

{
  "code": "authentication_required",
  "detail": "Bearer authentication is required.",
  "request_id": "1f9fcd64-c8b4-4d8f-98b1-3b7ed12cae38",
  "retryable": false,
  "status": 401,
  "title": "Unauthorized",
  "type": "https://api.data-platform.dev/problems/authentication-required",
  "instance": "/v1/vehicles/listings"
}

Errors

Every failure is an RFC 9457 problem document served as application/problem+json. The envelope is closed — no fields beyond the ones below ever appear — but key order is not stable, so parse the JSON rather than pattern-matching the string.

Shared error codes

These can be returned by any endpoint. Branch on code, which is stable, rather than on detail, which is prose.

Validation failures

A 400 request_validation_failed adds an invalid_params array pointing at each offending value. Unknown query parameters are an error, not a silently ignored extra — every query schema is closed.

{
  "code": "request_validation_failed",
  "detail": "The request did not match the operation contract.",
  "invalid_params": [
    { "name": "minLength", "pointer": "/state", "reason": "must NOT have fewer than 2 characters" }
  ],
  "request_id": "d890d9c9-e6f9-411b-9e47-e0d947868003",
  "retryable": false,
  "status": 400,
  "title": "Bad Request",
  "type": "https://api.data-platform.dev/problems/request-validation",
  "instance": "/v1/vehicles/market-value?make=Toyota&model=Camry&year=2021&state=T"
}

Retrying

Use the retryable boolean rather than the status code. Every 503 and the 429 set it to true; the 429 additionally carries a retry-after header in whole seconds. Client errors other than 429 are false — retrying them unchanged will fail identically. Retry with exponential backoff and jitter, and note that none of these endpoints mutate anything, so a retried GET is always safe.

Getting support on a failure

Every response carries an x-request-id header, and on failures the same UUID appears as request_id in the body. It is generated server-side — sending your own x-request-id has no effect and it will not be echoed. Log it. Because Authorization and Cookie headers are redacted from our logs, the request id is the only way we can locate your exact call.

Pricing & limits

Pricing is per successful call, metered at the endpoint level. There are no bundles and no minimums beyond the plan fee.

Plans

“Included calls” means calls with no per-call charge. Only Starter has any: 1,000 per UTC month, shared by all eleven synchronous vehicle data endpoints listed below. Pro and Scale include none. Those plans have no monthly call ceiling, but that is a volume allowance, not free usage — every successful call is metered at its per-endpoint rate on top of the monthly platform fee, and the fee buys throughput, endpoint access and support rather than calls.

Rate limiting is a token bucket keyed to your account, refilling at the plan’s requests-per-second rate. Exceeding it returns 429 rate_limit_exceeded with a retry-after header, and the reservation is released so the rejected request is free. There are no x-ratelimit-* headers.

Per-endpoint prices

Prices are per billing unit. The second figure in each cell is the equivalent cost per 1,000 billing units. A dash means the endpoint is not sold on that plan and returns403 plan_upgrade_required.

Included calls, credits, and running out

• The Starter plan’s 1,000 included monthly calls are shared by all eleven synchronous vehicle data endpoints above: VIN Decode, Search Vehicle Listings, Vehicle Photos, Specifications, Recalls & Safety, Market Value, Depreciation, Ownership Costs, Total Cost of Ownership, Loan & Payments, and Purchase Tax & Fees. The entitlement resets on the UTC calendar month.
• Every new account also receives a one-time $10 credit balance. It never resets, and after the shared allowance is used it funds successful calls at the published Starter rate. Plan-gated operations remain unavailable regardless of credit balance.
• When entitlement and credits together cannot cover a call, the request is refused with 402 insufficient_credits. That applies on every plan, not just Starter: metered data fees are always prepaid from credits, and a paid plan buys the rate limit, the lower unit prices and endpoint access rather than an overage bill.
• There is no machine-readable balance today. Your entitlement, credit balance and usage are visible only in the dashboard: the control-plane endpoints behind it require a dashboard session token, and a vdev_ API key presented there is rejected with 401 invalid_credential. Metered responses carry no balance or usage headers either — the only response headers this API sets beyond the standard ones are x-request-id, retry-after and cache-control. So a server-to-server integration cannot pre-flight or monitor burn-down; 402 insufficient_credits is the only programmatic signal, and you should handle it as an expected outcome rather than trying to predict it.
• Concurrency is safe. Reservations hold credit while a request is in flight, so parallel callers cannot oversubscribe a balance.

Vehicle history reports

Vehicle history is an asynchronous, account-owned workflow because provider coverage and preparation time vary by VIN. Creating the report requires a machine key with reports:order, as does explicitly retrying a durable local submitting job. Polling and reading the result require reports:read. A report ordered by one account is not visible to another.

Pricing

Pro: $1.99 per completed report. Scale: $0.99 per completed report. Starter accounts cannot order reports and receive 403 plan_upgrade_required. The charge settles only after canonical report JSON is stored; invalid or unsupported VINs, failed generations, and action_required outcomes cost $0.

curl -i https://api.vehicles.dev/v1/vehicles/history-reports \
  -X POST \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"vin":"1FTFW3L57TKD09376"}'

HTTP/2 202
location: /v1/vehicles/history-reports/7ae77ee8-94af-4c25-85f1-45a2ab1c6475
retry-after: 3

{
  "id": "7ae77ee8-94af-4c25-85f1-45a2ab1c6475",
  "vin": "1FTFW3L57TKD09376",
  "status": "queued",
  "hasResult": false,
  "retryAfterSeconds": 3,
  "replayed": false,
  "createdAt": "2026-08-16T12:00:00.000Z",
  "updatedAt": "2026-08-16T12:00:00.000Z"
}

# Poll status at the Retry-After cadence
curl -i https://api.vehicles.dev/v1/vehicles/history-reports/{id} \
  -H "Authorization: Bearer $VEHICLES_API_KEY"

# Only for a durable local status=submitting after an uncertain create response
curl -i -X POST https://api.vehicles.dev/v1/vehicles/history-reports/{id}/retry \
  -H "Authorization: Bearer $VEHICLES_API_KEY"

# Fetch canonical JSON only after status=completed and hasResult=true
curl -i https://api.vehicles.dev/v1/vehicles/history-reports/{id}/result \
  -H "Authorization: Bearer $VEHICLES_API_KEY"

Result data and coverage

The fixed result envelope is { "metadata": ReportMetadata, "report": Record<string, unknown> }. Metadata binds the stored result to its canonical VIN, provider, retrieval timestamp, schema version, and available coverage sections. The report value is the canonical provider object; Vehicles.dev does not rename its fields or discard provider-specific keys. Process report keys defensively and use metadata coverage rather than treating an absent section as a clean finding.

{
  "metadata": {
    "schemaVersion": "vehicle-history-report/v1",
    "provider": "vinexposed",
    "sources": ["vinexposed"],
    "vin": "1FTFW3L57TKD09376",
    "retrievedAt": "2026-08-16T12:03:00.000Z",
    "dataAsOf": null,
    "coverage": {
      "status": "partial",
      "availableSections": ["accidents", "equipment", "ownership"]
    }
  },
  "report": {
    "vehicle": { "year": 2012, "make": "Bentley", "model": "Continental GT" },
    "equipment": ["Navigation", "Heated seats"],
    "ownership": [{ "ownerNumber": 1, "country": "US" }],
    "titleBrands": ["rebuilt"],
    "odometerHistory": [{ "date": "2025-03-01", "mileage": 48110 }],
    "accidents": [{ "date": "2012-05-19", "severity": "minor" }],
    "theft": { "status": "clear" },
    "junkSalvageInsurance": { "records": [] },
    "recalls": [],
    "salesHistory": [{ "date": "2021-01-12", "amount": 52000 }],
    "marketAnalysis": { "averagePrice": 41200, "confidence": "high" }
  }
}

The example is representative, not exhaustive. Depending on provider coverage, a report may include these categories:

Idempotency, retries, and billing

• The workflow is available on Pro and Scale. Starter accounts receive 403 plan_upgrade_required; credits cannot unlock reports on Starter. Reports do not consume standard included calls.
• Reusing one Idempotency-Key with the same VIN returns the existing report. Reusing it for a different VIN returns 409 idempotency_conflict.
• If an uncertain create response leaves a durable local report in submitting, call POST /v1/vehicles/history-reports/{id}/retry. This endpoint resubmits with the original provider idempotency key; read-only status polling never performs a submission.
• Respect Retry-After. Reading the result before it is ready returns the retryable 409 report_not_ready; a provider throttle returns retryable429 report_rate_limited.
• Billing settles when a completed result is stored. Invalid or unsupported VINs, failed generations, and action_required outcomes do not settle a report charge.
• Coverage is conditional. When a title, accident, odometer, or ownership section is absent, present it as unavailable — never as a clean record.

Endpoint reference

11 synchronous endpoints in three groups. Each one lists its parameters, a runnable request, a real response captured from production, its own error codes, and the coverage caveats that matter when you build on it. The asynchronous history-report contract is documented separately above because it spans three resources.

curl -sS https://api.vehicles.dev/v1/vehicles/vin/5TDDZRBHXNS221317 \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -H "Accept: application/json"

{
  "origin": "store",
  "source": "carscrape",
  "vehicle": {
    "year": 2022,
    "make": "Toyota",
    "model": "Highlander",
    "trim": "Limited",
    "body_style": "SUV",
    "drivetrain": "AWD",
    "fuel": "Gasoline",
    "transmission": "Automatic",
    "cylinders": 6,
    "doors": 4
  },
  "vin": "5TDDZRBHXNS221317"
}

curl -sS https://api.vehicles.dev/v1/vehicles/specifications/5TDDZRBHXNS221317 \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -H "Accept: application/json"

{
  "source": "carscrape",
  "specifications": {
    "make": "TOYOTA",
    "model": "Highlander",
    "year": "2022",
    "trim": "Limited",
    "series": "75 Series",
    "body_class": "Sport Utility Vehicle [SUV]/Multipurpose Vehicle [MPV]",
    "doors": "5",
    "seats": "7",
    "drive_type": "4WD/4-Wheel Drive/4x4",
    "cylinders": "6",
    "displacement_l": "3.5",
    "engine_hp": "295",
    "fuel_primary": "Gasoline",
    "engine_config": "V-Shaped",
    "transmission_style": "Automatic",
    "transmission_speeds": "8",
    "gvwr": "Class 1D: 5,001 - 6,000 lb (2,268 - 2,722 kg)",
    "plant_country": "UNITED STATES (USA)",
    "manufacturer": "TOYOTA MOTOR MANUFACTURING, INDIANA, INC.",
    "vehicle_type": "MULTIPURPOSE PASSENGER VEHICLE (MPV)"
  },
  "vin": "5TDDZRBHXNS221317"
}

curl -sS https://api.vehicles.dev/v1/vehicles/recalls/5TDDZRBHXNS221317 \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -H "Accept: application/json"

{
  "count": 5,
  "make": "Toyota",
  "model": "Highlander",
  "recalls": [
    {
      "component": "EQUIPMENT:OTHER:LABELS",
      "summary": "Gulf States Toyota, Inc. (GST) is recalling certain 2022 4Runner, Tacoma, Highlander, and Highlander Hybrid vehicles. The load carrying capacity modification labels may not be permanent and can fade, becoming illegible.",
      "consequence": "An illegible label may allow the vehicle to be overloaded, increasing the risk of a crash.",
      "remedy": "GST will notify owners by mail, including a replacement load carrying capacity modification label for their vehicle and detailed replacement instructions, free of charge.",
      "campaign_number": "22V310000",
      "report_date": "06/05/2022"
    },
    {
      "component": "STRUCTURE:BODY:BUMPERS",
      "summary": "Toyota Motor Engineering & Manufacturing (Toyota) is recalling certain 2020-2023 Highlander & Highlander Hybrid vehicles. During normal vehicle operation, minor impact to the front lower bumper cover may result in the cover coming loose or detaching.",
      "consequence": "A detached front bumper cover can become a road hazard, increasing the risk of a crash.",
      "remedy": "Dealers will repair or replace the upper and lower front bumper covers as necessary, free of charge.",
      "campaign_number": "23V720000",
      "report_date": "26/10/2023"
    }
  ],
  "source": "carscrape",
  "vin": "5TDDZRBHXNS221317",
  "year": 2022
}

curl -sS -G https://api.vehicles.dev/v1/vehicles/market-value \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -d make=Toyota -d model=Camry -d year=2021 \
  -d miles=45000 -d trim=SE -d state=TX

{
  "currency": "USD",
  "estimateUsd": 26096,
  "inputs": {
    "year": 2021,
    "age": 5,
    "make": "Toyota",
    "model": "Camry",
    "trim": "SE",
    "miles": 45000,
    "miles_per_year": 9000,
    "condition": "used",
    "seller_type": "dealer",
    "state": "TX"
  },
  "medianApePct": 3.7,
  "source": "carscrape"
}

curl -sS -G https://api.vehicles.dev/v1/vehicles/depreciation \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -d make=Toyota -d model=Camry

{
  "annualDecay": 0.0652,
  "byModelYear": [
    { "year": 2026, "age": 0, "msrp": 33058, "median_price": 34779, "n_listings": 4038, "retention": 0.9788, "curve_beta": -0.06739, "confidence": 0.82 },
    { "year": 2025, "age": 1, "msrp": 32263, "median_price": 29399, "n_listings": 3416, "retention": 0.9588, "curve_beta": -0.06739, "confidence": 0.82 },
    { "year": 2024, "age": 2, "msrp": 30014, "median_price": 26370, "n_listings": 1841, "retention": 0.9233, "curve_beta": -0.06739, "confidence": 0.82 },
    { "year": 2016, "age": 10, "msrp": 25715, "median_price": 13490, "n_listings": 78, "retention": 0.5116, "curve_beta": -0.06739, "confidence": 0.99 },
    { "year": 2015, "age": 11, "msrp": 27605, "median_price": 13694, "n_listings": 87, "retention": 0.4741, "curve_beta": -0.06739, "confidence": 0.98 }
  ],
  "curveByAge": [
    { "age": 0, "retention": 0.979 },
    { "age": 1, "retention": 0.915 },
    { "age": 2, "retention": 0.855 },
    { "age": 5, "retention": 0.699 },
    { "age": 10, "retention": 0.499 },
    { "age": 12, "retention": 0.436 }
  ],
  "make": "Toyota",
  "model": "Camry",
  "source": "carscrape"
}

curl -sS -G https://api.vehicles.dev/v1/vehicles/ownership-costs \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -d make=Toyota -d model=Camry -d year=2021

{
  "annualFuelCostUsd": 2350,
  "co2GramsPerMile": 338,
  "combinedMpg": 26,
  "config": "Auto (S8), 6 cyl, 3.5 L",
  "fiveYearFuelCostUsd": 11750,
  "fuelType": "Regular",
  "make": "Toyota",
  "model": "Camry",
  "note": "Fuel/operating cost from EPA; excludes maintenance, insurance, and depreciation.",
  "source": "carscrape",
  "trimsAvailable": 1,
  "year": 2021
}

curl -sS -G https://api.vehicles.dev/v1/vehicles/total-cost-ownership \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -d year=2023 -d make=Honda -d model=Accord -d years=5 -d annual_miles=12000 -d state=TX

{
  "components": {
    "depreciation": { "amount": 12040.0, "basis": "measured" },
    "financingInterest": { "amount": null, "basis": "unavailable" },
    "fuel": { "amount": 7000.0, "basis": "published" },
    "insurance": { "amount": 7750.0, "basis": "reference", "perYear": 1550.0 },
    "maintenance": { "amount": 5700.0, "basis": "reference", "perMile": 0.095 },
    "repairs": { "amount": 2100.0, "basis": "reference", "perMile": 0.035 },
    "taxesAndFees": { "amount": 2600.0, "basis": "reference" }
  },
  "costPerMile": 0.619,
  "costPerYear": 7438.0,
  "measuredShareOfTotal": 0.513,
  "missingComponents": ["financingInterest"],
  "source": "carscrape",
  "total": 37190.0,
  "vehicleClass": "medium_sedan",
  "years": 5
}

curl -sS -G https://api.vehicles.dev/v1/vehicles/loan \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -d price=35000 -d down_payment=5000 -d apr=0.069 -d months=60

{
  "amountFinanced": 30000.0,
  "apr": 0.069,
  "interestByYear": [1907.47, 1536.82, 1139.77, 714.43, 258.81],
  "monthlyPayment": 592.62,
  "months": 60,
  "source": "carscrape",
  "totalInterest": 5557.29,
  "totalPaid": 35557.29,
  "tradeInEquity": 0.0
}

curl -sS -G https://api.vehicles.dev/v1/vehicles/purchase-costs \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -d price=40000 -d state=TX -d trade_in_value=10000

{
  "documentationFee": 500.0,
  "feesTotal": 850.0,
  "rateTableAsOf": "2026-01-01",
  "salesTax": 1875.0,
  "source": "carscrape",
  "state": "TX",
  "taxRate": 0.0625,
  "taxRateBasis": "reference_table",
  "taxableBase": 30000.0,
  "titleAndRegistration": 350.0,
  "total": 2725.0,
  "tradeInReducesTaxableAmount": true
}

curl -sS -G https://api.vehicles.dev/v1/vehicles/listings \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -d make=Ford -d model=F-150 -d state=CT -d year_min=2026 \
  -d sort=price -d order=desc -d limit=1

{
  "count": 1,
  "limit": 1,
  "offset": 0,
  "results": [
    {
      "vin": "1FTFW7L83TFA89342",
      "year": 2026,
      "make": "Ford",
      "model": "F-150",
      "trim": "Platinum",
      "body_style": "Truck",
      "fuel": "Gasoline",
      "drivetrain": "4WD",
      "transmission": "Automatic",
      "color": "Gray",
      "price": 77101,
      "miles": 9,
      "condition": "new",
      "title_status": null,
      "seller_type": "dealer",
      "dealer_name": "Shaker Family Ford Lincoln",
      "city": "Watertown",
      "state": "CT",
      "zip": null,
      "lat": 41.5922,
      "lng": -73.10814,
      "segment": "mainstream",
      "is_active": 1,
      "days_on_market": 3,
      "data_quality": 1.0,
      "vdp_url": "https://www.autolist.com/ford-f+150#vin=1FTFW7L83TFA89342",
      "source": "autolist",
      "vin_valid": 1
    }
  ],
  "source": "carscrape",
  "total": 12
}

curl -sS https://api.vehicles.dev/v1/vehicles/photos/1FTFW3L57TKD09376 \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -H "Accept: application/json"

{
  "galleryComplete": false,
  "galleryCount": 3,
  "listingSource": "autolist",
  "listingUrl": "https://www.autolist.com/ford-f+150#vin=1FTFW3L57TKD09376",
  "photoCount": 39,
  "photos": [
    "https://static.cargurus.com/images/forsale/2026/07/18/07/13/2026_ford_f-150-pic-6182805071162814707-1024x768.jpeg",
    "https://static.cargurus.com/images/forsale/2026/07/18/07/13/2026_ford_f-150-pic-3355019284471120388-1024x768.jpeg",
    "https://static.cargurus.com/images/forsale/2026/07/18/07/13/2026_ford_f-150-pic-8821004417720935512-1024x768.jpeg"
  ],
  "primaryImage": "https://static.cargurus.com/images/forsale/2026/07/18/07/13/2026_ford_f-150-pic-6182805071162814707-1024x768.jpeg",
  "source": "carscrape",
  "vin": "1FTFW3L57TKD09376"
}

MCP server

Connect Vehicles.dev to any MCP-capable AI agent — Claude Desktop, Claude Code, Cursor, or one you write yourself — so it can look up vehicle data by being asked, instead of by being programmed.

The server is a local process that speaks the Model Context Protocol over stdio. It exposes the 11 synchronous endpoints plus the durable report workflow as 15 tools, each carrying a description precise enough for a model to pick the right one and fill its arguments unaided. Your key stays in the server’s own environment: the agent never sees it, and every tool call is a direct request from your machine to https://api.vehicles.dev with nothing proxied in between.

Setup

The package is vehicles-dev-mcp, published on npm under the MIT licence. The configurations below run it with npx, so there is nothing to install or build first — your MCP client fetches it on launch. Node.js 20 or newer is required.

npm install -g vehicles-dev-mcp

Installing globally puts a vehicles-dev-mcp binary on your PATH, which you can use in place of npx in any configuration below. It is only worth doing if you would rather pin the version yourself than let your client fetch the latest on launch.

Environment

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (on Windows, %APPDATA%\Claude\claude_desktop_config.json), then restart the app — it reads this file only at launch.

{
  "mcpServers": {
    "vehicles-dev": {
      "command": "npx",
      "args": ["-y", "vehicles-dev-mcp"]
    }
  }
}

If the tools do not appear, the reason is on stderr in ~/Library/Logs/Claude/mcp-server-vehicles-dev.log. A missing or blank VEHICLES_API_KEY is the usual cause, and the server names the fix there rather than starting in a broken state.

Claude Code

claude mcp add --transport stdio vehicles-dev \
  -- npx -y vehicles-dev-mcp

Add --scope project to write a committable .mcp.json instead of your personal configuration. Verify with claude mcp list, or /mcp inside a session. Note the argument ordering: never put the server name directly after --env — keep another flag (here --transport) between them.

Cursor, VS Code and everything else

Any client that launches a stdio MCP server works. Cursor reads .cursor/mcp.json using the same object shape as Claude Desktop above; VS Code 1.99+ in Agent mode reads .vscode/mcp.json, which nests servers under a servers key and wants an explicit "type": "stdio" alongside command, args and env. The command, arguments and environment are identical in all three.

Tools

14 read-only GET tools are annotated readOnlyHint. The remaining report-order tool is idempotent and makes no API call unless confirm_order=true; callers must supply and reuse a stable UUID. Successful results preserve the API JSON as both text and structured content. A non-2xx becomes an isError result carrying structured status, machine code, request_id, retry timing, and a recovery hint so an agent can repair or resume the workflow safely.

A worked example

Ask your agent, in whatever words you like:

What's a 2022 F-150 with 20k miles worth?

• The agent matches the question against the 15 tool descriptions and selects get_market_value on its own. You never name the tool, and nothing about the wording has to be exact.
• It fills the tool's schema from your sentence. The schema states that model is matched case-sensitively against our canonical naming, so it sends "F-150" rather than "f150", and it converts "20k miles" to the integer 20000.
• The server issues one GET to https://api.vehicles.dev/v1/vehicles/market-value with your key on the Authorization header, and returns the response body to the agent verbatim.
• The agent reads estimateUsd for the number and the inputs echo to confirm which of its arguments the model actually scored, then answers in prose — normally flagging that this is an asking price from live dealer listings rather than a sale price, because the tool description says so.
• Add a state and it improves: "…worth in Texas?" makes the agent send state: "TX", uppercase, as the schema requires. Ask "and what is actually listed near me?" and it follows up with search_listings — a second tool call, and a second billable request.

{
  "name": "get_market_value",
  "arguments": {
    "make": "Ford",
    "model": "F-150",
    "year": 2022,
    "miles": 20000
  }
}

Remote MCP via the Claude API

The Claude API can attach a remote MCP server to a message — Anthropic makes the connection server-side, so no local process is involved. That requires an MCP endpoint reachable over HTTPS. The Vehicles.dev deployment is configured for https://mcp.vehicles.dev/mcp; the Render service, DNS and TLS must be live before clients can use it.

The request has two halves that must agree. mcp_servers declares the connection; a matching mcp_toolset entry in tools grants access to it. Both are required — omitting the toolset is a validation error, not a silent no-op — and the beta header mcp-client-2025-11-20 gates the whole feature.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "mcp_servers": [
      {
        "type": "url",
        "name": "vehicles-dev",
        "url": "https://mcp.vehicles.dev/mcp",
        "authorization_token": "vdev_your_key_here"
      }
    ],
    "tools": [
      { "type": "mcp_toolset", "mcp_server_name": "vehicles-dev" }
    ],
    "messages": [
      { "role": "user", "content": "What is a 2022 Ford F-150 with 20,000 miles worth?" }
    ]
  }'

mcp_server_name must match the name on the server entry exactly; that string is how the toolset binds to the connection. Keep the credential in authorization_token, never in the prompt. If you prefer to keep the key and MCP connection entirely on your own machine, the stdio setup above remains available.

Conventions

• Money. Data endpoints return whole US dollars — estimateUsd, annualFuelCostUsd, listing price. Billing and pricing figures are quoted in USD micros elsewhere in the platform, where 1,000,000 micros is $1. Do not mix the two.
• Naming. The top-level envelope is camelCase. Pass-through objects and arrays — vehicle, specifications, inputs, results, observations, recalls, identity, byModelYear elements — keep their upstream snake_case keys. That asymmetry is deliberate and stable.
• Nulls. null is a first-class “unknown”. Some objects omit null keys entirely rather than emitting them, so treat every nested field as optional.
• Dates. ISO-8601 strings throughout. The one exception is recall report_date, which NHTSA supplies in inconsistent formats and we pass through verbatim.
• Pagination. Only Search Vehicle Listings paginates, via limit (1–500, default 50) and offset against the total match count. No cursors, no Link headers. Every other endpoint is a single-object lookup.
• Query handling. Query strings are coerced to the declared integer and boolean types, and unknown parameters are rejected rather than dropped. VINs in the path are upper-cased server-side.
• Timeouts. Each endpoint has an upstream budget of 5, 10 or 15 seconds, listed on the endpoint. Set your client timeout above the endpoint’s budget so you receive the API’s 503 rather than timing out blind.
• Idempotency. Every data endpoint is a GET and safe to repeat. The metering layer is internally idempotent on the request id, so a retry never double-charges a single request.

Versioning, availability & freshness

What we will change, what it costs when we change prices, what we do not promise about uptime, and how current the data actually is. Read this before you put the API on a critical path.

Versioning & changes

There is one API version. The /v1/ path prefix is the contract — there is no version header, no date-pinned version, and no per-account pinning.

• Additive changes ship without notice. New endpoints, new fields on an existing response, new optional query parameters and new code values on an existing status can appear at any time. Parse defensively: ignore unknown JSON fields, and fall back to the HTTP status when you meet a code you do not recognize.
• Breaking changes are removing an endpoint, removing or renaming a response field, adding a required parameter, tightening an existing parameter’s constraints, changing a field’s type, or changing what an existing code means. Note that a nested value going null — or a key disappearing from an object that omits nulls — is not a breaking change; every nested field is documented as optional for that reason.
• There is no changelog page and no contractual deprecation window on self-serve plans today. If your integration needs advance written notice before a breaking change, email support@vehicles.dev and we will agree a notice period in writing rather than leaving you to discover it in production.

When prices change

The 2026-08-18 shown as Price catalog in the header is the version of the pricing catalog this page was generated from. Prices are not quoted live at call time: your subscription pins a catalog version, every metered event records the unit price that was actually applied, and a new catalog is adopted at the start of your next UTC monthly period. A price change therefore never reprices calls you have already made, and it never takes effect mid-period.

Availability

We publish no uptime target, status page or incident channel today, and self-serve plans carry no SLA. What you get instead is explicit failure: every dependency outage surfaces as a documented 503 with retryable: true rather than as a hang or a silently degraded body, upstream calls are bounded by the per-endpoint timeout listed above, and the x-request-id on every response is how we trace an incident. Report an outage to support@vehicles.dev with a request id and a UTC timestamp. If you need a contractual uptime commitment, ask before you build.

Data freshness

• Live upstream, uncached. Vehicle Specifications, Recalls & Safety and Ownership Costs call NHTSA vPIC, the NHTSA recalls API and EPA fueleconomy.gov on every request, as does the "vpic" fallback inside VIN Decode. They are exactly as current — and as available — as those agencies are.
• Store-backed, crawl-paced. Listings, Photos and the store-origin path of VIN Decode come from our own continuously running crawl. We do not publish a maximum staleness, and no listings field carries a crawl timestamp: is_active tells you the row was still live at the last crawl pass that covered it, not when that pass ran, and days_on_market counts from our first observation rather than the dealer’s listing date.
• Precomputed. Depreciation is a periodically rebuilt table and Market Value is a periodically retrained model; both are refreshed on our schedule rather than per request, so two identical calls minutes apart will agree.
• If your use case needs a hard freshness bound or a per-row crawl timestamp, say so before you build on these endpoints — neither is available through the API today.

Support

Email support@vehicles.dev. To get a fast, specific answer, include:

• the x-request-id (or request_id) of a failing call — this is the single most useful thing you can send;
• the approximate UTC timestamp of the request;
• the endpoint and the parameters you sent, with the API key redacted to its last four characters.

Never send us a full API key. If one has leaked, revoke it in the dashboard and mint a replacement — revocation is immediate.

Usage terms

• Standard plans cover use inside your own product or internal systems. Bulk redistribution or resale of raw records needs a separate written agreement.
• Photo URLs point at CDNs owned by the source marketplace. We link to them; we do not license the imagery, and it is not ours to sublicense.
• Specifications, recalls and ownership costs are derived from public NHTSA and EPA data and are passed through with their own accuracy limits, which are described on each endpoint.
• This page is the current statement of usage rights — there is no separate terms-of-service, acceptable-use or DPA page yet. For a redistribution licence, a data-processing agreement, or vendor-security paperwork, email support@vehicles.dev and we will put it in writing.

Machine-readable spec

The OpenAPI 3.1 document is generated from the same schemas that validate every request and is served unauthenticated at https://api.vehicles.dev/openapi.json. It declares https://api.vehicles.dev as its server, so you can import it into Postman or Insomnia, or point a client generator at it, without hand-editing a base URL.

curl -sS https://api.vehicles.dev/openapi.json -o vehicles-openapi.json

Get an API keyCompare plans