carstat-app VIN Decoding API

openapi: 3.2.0
info:
  title: REST API Reference VIN Decoding API
  version: v1
  description: 'API for accessing vehicle specifications, NHTSA recalls, and NHTSA safety ratings. All three data verticals share the same discoverable browsing pattern: list available years → list makes for a year → list models for a year + make → fetch data.'
  x-rate-limit:
    requests: 120
    period: minute
    description: shared by REST and MCP across all account credentials
  x-logo:
    url: logo.svg
    backgroundColor: '#FFFFFF'
    href: /
  contact:
    name: Carstat API Support
    email: support@carstat.app
servers:
- url: https://api.carstat.app
  description: Production server
security:
- bearer_auth: []
tags:
- name: VIN Decoding
  description: Decode a VIN into its manufacturer, model, model year, origin and build plant. It answers for vehicle classes the specification catalog does not cover.
paths:
  /v1/vin-decode/{vin}:
    get:
      summary: Decode a VIN
      tags:
      - VIN Decoding
      description: Decodes a VIN into the vehicle it identifies — manufacturer, model, model year, country of manufacture, vehicle class, series/trim labels and the build plant.
      operationId: decodeVin
      security:
      - bearer_auth: []
      parameters:
      - name: vin
        in: path
        description: Vehicle Identification Number (VIN), a 17-character string that uniquely identifies a vehicle
        required: true
        example: 4T1BF1FK5CU123456
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/vin_decode_response'
        '402':
          description: Insufficient prepaid credits; the query is not charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/insufficient_credits_error'
        '503':
          description: Query pricing is temporarily unavailable; the query is not charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: No activated prepaid credits or account under review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: Returned when the VIN cannot be decoded at all, for example an unrecognised manufacturer prefix or an incorrect VIN length
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '400':
          description: VIN could not be decoded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
      - error
    insufficient_credits_error:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Insufficient credits. Please top up your balance.
        code:
          type: string
          enum:
          - insufficient_credits
          description: Top up your prepaid balance to continue querying
      required:
      - error
      - code
    vin_decode_response:
      type: object
      description: 'A decoded VIN. Returned by GET /v1/vin-decode/{vin}, which performs no specification lookup: use it to identify or validate a VIN cheaply, and for vehicles the specification catalog does not cover. Every field is decoded from the VIN itself: the vehicle it identifies, the registered manufacturer and origin, the vehicle class, the VIN''s own series/trim labels, the engine manufacturer, the check-digit verification and the manufacturing (build) plant. Body type, doors, drivetrain, fuel and engine specifications are not included: those are vehicle specifications, available from the specification endpoints. Each field is null when it cannot be determined from the VIN.'
      properties:
        vin:
          type: string
          description: The VIN that was decoded, upper-cased.
        errors:
          type: array
          items:
            type: string
          description: Non-fatal VIN validation warnings, if any.
        make:
          type:
          - string
          - 'null'
          description: Manufacturer decoded from the VIN
        model:
          type:
          - string
          - 'null'
          description: Model decoded from the VIN, normalised to the name used in the catalog. Null when the VIN identifies the manufacturer but not a specific model.
        year:
          type:
          - integer
          - 'null'
          description: Model year decoded from VIN position 10
        wmi:
          type:
          - string
          - 'null'
          description: World Manufacturer Identifier (VIN positions 1-3).
        manufacturer:
          type:
          - string
          - 'null'
          description: Registered manufacturer name, e.g. "TESLA, INC." — distinct from the vehicle make/brand.
        region:
          type:
          - string
          - 'null'
          description: Geographic region of manufacture, e.g. "ASIA", "NORTH AMERICA", "EUROPE".
        country:
          type:
          - string
          - 'null'
          description: Manufacturing country decoded from the VIN/WMI.
        vehicle_type:
          type:
          - string
          - 'null'
          description: Vehicle class registered for this VIN, e.g. "Passenger Car", "Truck", "Multipurpose Passenger Vehicle (MPV)". A broader classification than the body type in the spec candidates.
        series:
          type:
          - string
          - 'null'
          description: Vehicle series / sub-model as decoded from the VIN.
        trim:
          type:
          - string
          - 'null'
          description: Trim level as decoded from the VIN.
        engine_manufacturer:
          type:
          - string
          - 'null'
          description: Company that built the engine, which is not always the vehicle's make. Not available for all manufacturers.
        check_digit:
          type:
          - object
          - 'null'
          description: Verification of the VIN's check digit (position 9), which is derived from the other 16 characters. A mismatch usually means the VIN was mistyped or transcribed incorrectly; `expected` gives the character the rest of the VIN implies. Decoding still proceeds, since some regions do not use a check digit.
          properties:
            actual:
              type:
              - string
              - 'null'
              description: Check digit character present in the supplied VIN (VIN position 9).
            expected:
              type:
              - string
              - 'null'
              description: Check digit character the rest of the VIN implies.
            is_valid:
              type:
              - boolean
              - 'null'
              description: Whether the supplied check digit matches the expected one.
        plant:
          type:
          - object
          - 'null'
          description: Manufacturing (build) plant decoded from the VIN. Null when the VIN does not encode a plant for this vehicle (not available for all manufacturers).
          properties:
            country:
              type:
              - string
              - 'null'
              description: Plant country.
            city:
              type:
              - string
              - 'null'
              description: Plant city.
            state:
              type:
              - string
              - 'null'
              description: Plant state or province. Not available for all plants.
            code:
              type:
              - string
              - 'null'
              description: Plant code (VIN position 11).
            manufacturer:
              type:
              - string
              - 'null'
              description: Plant operator/manufacturer.
      required:
      - vin
      - errors
      - make
      - model
      - year
      - wmi
      - manufacturer
      - region
      - country
      - vehicle_type
      - series
      - trim
      - engine_manufacturer
      - check_digit
      - plant
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: API Token
      description: API token authentication. Get your token from the dashboard.