GET /vehicle/vin/decode

Decodes a 17-character VIN into structured vehicle data: the World Manufacturer Identifier and manufacturer, assembly country and region, model year, check-digit validity and any deterministic positional attributes the tables resolve. The decode is served from a local store built from the official NHTSA vPIC dataset (US public domain), so a covered VIN resolves in milliseconds without an account or API key. The runtime performs no network call and holds no secret.

Use it when an agent needs a grounded answer to questions such as “who built this vehicle and where?”, “what model year is this VIN?” or “does this VIN pass its check digit?” - for example vetting a single used-car listing, where the classic auto-data APIs sit behind a B2B subscription an agent cannot sign up for. Lookup is by VIN only; there is no lookup by licence plate. See the live /catalog for the authoritative endpoint listing and price.

x402 golden rule: the agent pays for the answer to its question. A VIN the service can decode is a successful answer -> 200, including a partial decode where only the WMI and a few attributes resolve. Requests the service cannot answer - a missing or malformed VIN, or a well-formed VIN whose manufacturer is absent from the tables - leave the 200 range and are not billed.

Parameters

GET /vehicle/vin/decode?vin=1HGCM82633A004352

200 response - UnifiedResponse

{
  "data": { ... },
  "provenance": {
    "source": "nhtsa-vpic",
    "fetched_at": "2026-06-20T12:00:00Z",
    "freshness": { "kind": "snapshot", "as_of": "2026-06-01T00:00:00Z" }
  }
}

• provenance.source: nhtsa-vpic, the served vPIC store.
• freshness.kind: snapshot; as_of is the store dump date that backed the answer.
• Vehicle data is derived from the NHTSA vPIC tables, which are US public domain.

Fields of data

Optional fields that cannot be resolved are omitted, never guessed. The decode does not oversell: an unresolved field is simply absent.

coverage

Example - fully decoded VIN

{
  "data": {
    "vin": "1HGCM82633A004352",
    "wmi": "1HG",
    "manufacturer": "Honda",
    "make": "Honda",
    "country": "United States",
    "region": "North America",
    "model_year": 2003,
    "check_digit_valid": true,
    "attributes": { "Model": "Civic" },
    "coverage": { "complete": true }
  },
  "provenance": {
    "source": "nhtsa-vpic",
    "fetched_at": "2026-06-20T12:00:00Z",
    "freshness": { "kind": "snapshot", "as_of": "2026-06-01T00:00:00Z" }
  }
}

Example - partial decode is still a 200

When only part of the VIN resolves, the answer is still a success. The manufacturer and any resolved attributes are returned, the unresolved field is omitted, and coverage states honestly what is missing.

{
  "data": {
    "vin": "WVWZZZ1JZ0W000001",
    "wmi": "WVW",
    "manufacturer": "Volkswagen",
    "check_digit_valid": false,
    "attributes": { "Model": "Golf" },
    "coverage": {
      "complete": false,
      "reason": "model year could not be disambiguated from the snapshot"
    }
  },
  "provenance": {
    "source": "nhtsa-vpic",
    "fetched_at": "2026-06-20T12:00:00Z",
    "freshness": { "kind": "snapshot", "as_of": "2026-06-01T00:00:00Z" }
  }
}

Check digit is information, not a gate

check_digit_valid reports whether the VIN’s position-9 check digit is consistent with the other characters. It is returned as information: a VIN whose check digit is invalid is still decoded and still returns 200. The field lets a caller flag a possibly mistyped or altered VIN; the service never turns it into an error.

Coverage honesty

The service answers from a local snapshot of the vPIC tables. It does not query NHTSA at request time, does not infer values from make or model, and does not guess. A field it cannot resolve is omitted, and coverage.complete: false names what was missing (for example a model year the 30-year cycle could not disambiguate).

Scope is deliberately bounded to what the public tables decode deterministically: there is no lookup by licence plate and no paid B2B registry behind this endpoint. Purely structural facts an LLM can already derive from the VIN itself (a well-formed VIN whose WMI is simply absent from the tables) are not sold as a paid answer - they return 404.

Errors

Only requests the service cannot answer leave the 200 range. A malformed VIN and an unknown WMI are not billed.

{ "error": "query parameter `vin` is required (17-character VIN)", "code": "MISSING_PARAMETER" }

{ "error": "invalid VIN `1HGCM82633A00435`; expected 17 characters over the VIN alphabet (no I, O, Q)", "code": "INVALID_VIN" }

{ "error": "no manufacturer found for WMI `JHM` in the vPIC store", "code": "UNKNOWN_WMI" }

Attribution

Vehicle decoding data is derived from the NHTSA vPIC (Vehicle Product Information Catalog) tables, published by the US National Highway Traffic Safety Administration in the public domain.

See also

• GET /vehicle/recalls - candidate recall campaigns for a vehicle, consolidated offline from public sources.
• GET /vehicle/report - a composite report for one VIN (decode + recalls + Crit’Air) in a single settlement.
• For agents - discovery surfaces, the live /catalog and how settlement works.