# Vehicles.dev

> Paid, server-to-server REST API for US vehicle data: VIN decode, factory specifications, NHTSA
> recalls, ML market value, depreciation curves, EPA ownership costs, live dealer listings, listing
> price history, hero photos, a legacy composite report, and an asynchronous provider-backed vehicle
> history report. Backed by a continuously crawled dealer-listings store (~1.72M normalized listings,
> ~4.69M price/mileage observations) joined against NHTSA vPIC, the NHTSA recalls API and EPA
> fueleconomy.gov. OpenAPI 3.1 served unauthenticated; RFC 9457 problem documents on every failure.

Generated by API Evangelist from the provider's public surface — https://vehicles.dev/llms.txt
returned HTTP 404 on 2026-08-16, so no provider-published llms.txt exists.

Important: the API is deliberately NOT browser-callable. No CORS headers are served, cookie auth is
rejected, and any request carrying an `Origin` header is refused. Call it from a backend.

## APIs

- [Vehicles.dev API base](https://api.vehicles.dev): Single production host. All machine operations
  live under `/v1/`. One version; the path prefix is the contract — no version header, no date pinning.
- [OpenAPI 3.1 document](https://api.vehicles.dev/openapi.json): Unauthenticated, generated from the
  same schemas that validate every request. Declares `https://api.vehicles.dev` as its server. Covers
  the whole platform — generate clients from the `/v1/vehicles/` paths and drop the rest.

## Vehicle data endpoints (API key)

- `GET /v1/vehicles/vin/{vin}` — VIN Decode. Canonical identity: year, make, model, trim, body style,
  drivetrain, fuel, transmission, cylinders, doors. `origin: "store"` when served from the crawled
  dataset, `"vpic"` when decoded live against NHTSA.
- `GET /v1/vehicles/specifications/{vin}` — Vehicle Specifications. Raw NHTSA vPIC spec sheet.
- `GET /v1/vehicles/recalls/{vin}` — Recalls & Safety. Matched at year/make/model level, not per VIN.
- `GET /v1/vehicles/market-value` — Market Value. Gradient-boosted **asking**-price estimate (3.7%
  median absolute percentage error on holdout), not a realized transaction price.
- `GET /v1/vehicles/depreciation` — Depreciation. Per make and model, not per trim or VIN.
- `GET /v1/vehicles/ownership-costs` — Ownership Costs. EPA annual/five-year fuel cost, combined MPG,
  CO2. Fuel only.
- `GET /v1/vehicles/listings` — Search Vehicle Listings. The only paginated endpoint: `limit` (1-500,
  default 50) and `offset` against `total`.
- `GET /v1/vehicles/history/{vin}` — Listing Price History. Scale plan only; other plans get 403.
- `GET /v1/vehicles/photos/{vin}` — Vehicle Photos. One hero image, not a gallery.
- `GET /v1/vehicles/report/{vin}` — Legacy Composite Vehicle Report.
- `POST /v1/vehicles/history-reports` — Order a provider-backed vehicle history report. 202 + stable
  id + `Location` + `Retry-After`. Requires a UUID `Idempotency-Key`. Then poll
  `GET /v1/vehicles/history-reports/{id}` until `status=completed` and `hasResult=true`, and read
  `GET /v1/vehicles/history-reports/{id}/result`.

## Authentication

- Bearer only: `Authorization: Bearer <key>`. Case-sensitive `Bearer`, exactly one space.
- Product keys are prefixed `vdev_` and are product-scoped; a key from another product returns
  `401 invalid_credential`.
- No query-string keys, no basic auth, no cookies. A `Cookie` header returns
  `401 cookie_credentials_rejected`.
- Rotation is create-then-revoke; revocation is immediate. Limits are per account, not per key.
- Control-plane (`/v1/control/*`) and operator (`/v1/ops/*`) routes require a WorkOS dashboard session
  token and reject a `vdev_` key.

## Errors

RFC 9457 `application/problem+json`, closed envelope: `code`, `detail`, `instance?`, `invalid_params?`,
`request_id`, `retryable`, `status`, `title`, `type`. Branch on `code`, never on `detail` or `type`.
Every response — success or failure — carries an `x-request-id` header.

Shared codes: `request_validation_failed` (400), `authentication_required` (401),
`invalid_credential` (401), `cookie_credentials_rejected` (401), `invalid_origin` (401),
`insufficient_credits` (402), `plan_upgrade_required` (403), `subscription_inactive` (403),
`route_not_found` (404), `rate_limit_exceeded` (429), `internal_error` (500),
`authentication_unavailable` (503).

## Plans, pricing and limits

- Starter — $0/mo, 1,000 included calls/month (VIN Decode, Search Listings, Photos only), 5 req/s.
- Pro — $299/mo, no included calls, 10 req/s, 14-day trial.
- Scale — $599/mo, no included calls, 50 req/s, 14-day trial. Only plan with Listing Price History.
- Every endpoint is `successOnly`: billed on 2xx, free on any 4xx/5xx including 429.
- Metered fees are prepaid from credits on every plan; exhaustion is `402 insufficient_credits`.
- Rate limiting is a per-account token bucket. Exceeding it returns `429 rate_limit_exceeded` with a
  `retry-after` header. **There are no `x-ratelimit-*` headers** and no machine-readable balance.

## Agents / MCP

- MCP server: `vehicles-dev-mcp` on npm (MIT, v0.1.0, 2026-08-14). **Local stdio only** —
  `npx -y vehicles-dev-mcp` with `VEHICLES_API_KEY` in the environment. Ten read-only tools, one per
  data endpoint. The documented remote endpoint `https://mcp.vehicles.dev/mcp` does not resolve
  (DNS NXDOMAIN, probed 2026-08-16), so there is no hosted agent surface today.
- No A2A agent card, no `/.well-known/*` documents, no GraphQL, no AsyncAPI, no consumer webhooks.

## Docs

- [API reference](https://vehicles.dev/docs)
- [Quickstart](https://vehicles.dev/docs#quickstart)
- [Authentication](https://vehicles.dev/docs#authentication)
- [Errors](https://vehicles.dev/docs#errors)
- [Pricing & limits](https://vehicles.dev/docs#pricing)
- [Vehicle history reports](https://vehicles.dev/docs#vehicle-history-reports)
- [MCP server](https://vehicles.dev/docs#mcp)
- [Conventions](https://vehicles.dev/docs#conventions)
- [Versioning, availability & freshness](https://vehicles.dev/docs#lifecycle)
- [Support & usage terms](https://vehicles.dev/docs#support-terms)
- [Plans](https://vehicles.dev/#pricing)
- [Sign up](https://vehicles.dev/auth/sign-up)
- Support: support@vehicles.dev — always include the `x-request-id` and a UTC timestamp.

## Optional

- [API Evangelist profile](https://apis.io/provider/vehicles-dev-api/)
- No status page, no SLA, no changelog, no deprecation window on self-serve plans (provider states
  this explicitly). No separate terms-of-service, acceptable-use or DPA page yet.