---
openapi: 3.0.1
info:
  title: REST API Reference
  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
tags:
- name: Vehicle Specifications
  description: Retrieve full 250+ field engineering specifications. Browse years →
    makes → models → modifications to get a modification_id, then fetch the full spec
    sheet. Also supports metric-based search.
- 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.
- name: Recalls
  description: Browse and retrieve NHTSA recall campaigns. Use the discovery endpoints
    (years → makes → models) to navigate available data, then fetch all recall campaigns
    for a specific vehicle.
- name: Safety Ratings
  description: Browse and retrieve NHTSA 5-star crash test ratings. Use the discovery
    endpoints (years → makes → models) to navigate available data, then fetch frontal,
    side, pole, and rollover ratings for a specific vehicle.
paths:
  "/v1/specs/makes/{year}":
    get:
      summary: List makes for a year
      tags:
      - Vehicle Specifications
      description: Returns a list of vehicle manufacturers (makes) that have models
        available for the specified year.
      operationId: getMakesByYear
      security:
      - bearer_auth: []
      parameters:
      - name: year
        in: path
        description: Model year (e.g., 2024)
        required: true
        example: 2024
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                - Acura
                - Audi
                - BMW
                - Chevrolet
                - Ford
                - Honda
                - Toyota
                description: Array of make names in alphabetical order
        '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"
  "/v1/specs/models/{year}/{make}":
    get:
      summary: List models for a year and make
      tags:
      - Vehicle Specifications
      description: Returns a list of vehicle models available for the specified year
        and manufacturer.
      operationId: getModelsByYearMake
      security:
      - bearer_auth: []
      parameters:
      - name: year
        in: path
        description: Model year (e.g., 2024)
        required: true
        example: 2024
        schema:
          type: integer
      - name: make
        in: path
        description: Vehicle manufacturer name (e.g., Toyota)
        required: true
        example: Toyota
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                - 4Runner
                - Camry
                - Corolla
                - Highlander
                - RAV4
                - Tacoma
                - Tundra
                description: Array of model names in alphabetical order
        '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"
        '404':
          description: make not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/v1/specs/modifications/{year}/{make}/{model}":
    get:
      summary: List modifications for a vehicle
      tags:
      - Vehicle Specifications
      description: Returns the engine/powertrain configurations (modifications) available
        for the specified year, make and model. Use a returned modification ID to
        fetch the full specification sheet.
      operationId: getModificationsByYearMakeModel
      security:
      - bearer_auth: []
      parameters:
      - name: year
        in: path
        description: Model year (e.g., 2024)
        required: true
        example: 2024
        schema:
          type: integer
      - name: make
        in: path
        description: Vehicle manufacturer name (e.g., Toyota)
        required: true
        example: Toyota
        schema:
          type: string
      - name: model
        in: path
        description: Vehicle model name (e.g., Camry)
        required: true
        example: Camry
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Engine/powertrain configuration name
                    modification_id:
                      type: string
                      format: uuid
                      description: Unique modification identifier to use for spec
                        lookups
                  required:
                  - name
                  - modification_id
                example:
                - name: 2.0 (173 Hp) Direct Shift CVT
                  modification_id: 11111111-1111-5111-8111-111111111111
                - name: 2.5 (218 Hp) Hybrid e-CVT
                  modification_id: 22222222-2222-5222-8222-222222222222
                description: Array of engine/powertrain configurations with their
                  unique IDs
        '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"
        '404':
          description: model not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/v1/specs/{modification_id}":
    get:
      summary: Get vehicle specifications by modification ID
      tags:
      - Vehicle Specifications
      description: Returns detailed vehicle specifications for a specific modification.
        Use the modification ID returned by the modifications listing endpoint.
      operationId: getVehicleSpecs
      security:
      - bearer_auth: []
      parameters:
      - name: modification_id
        in: path
        format: uuid
        description: UUID returned by the modifications listing endpoint
        required: true
        example: 11111111-1111-5111-8111-111111111111
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/vehicle_specs_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"
        '404':
          description: modification not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: No activated prepaid credits
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/v1/specs/vin/{vin}":
    get:
      summary: Search vehicle specifications by VIN
      tags:
      - Vehicle Specifications
      description: 'Searches the specification catalog by VIN and returns every published
        specification sheet that matches the vehicle the VIN identifies — engine,
        dimensions, fuel economy, drivetrain and the rest of the 250+ fields, plus
        the single most likely match. This is a specification search keyed on a VIN,
        not VIN decoding: for the VIN''s own decoded attributes — manufacturer, country
        of manufacture, vehicle class, series and trim labels, check digit and build
        plant — call GET /v1/vin-decode/{vin} instead. Requires credit access; charged
        at the published specifications-by-VIN rate.'
      operationId: getVehicleSpecsByVin
      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: 1HGCM82633A123456
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/vin_specs_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"
        '404':
          description: Returned when the VIN is valid but no specifications are published
            for that vehicle
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/vin_no_specs_error"
        '422':
          description: invalid VIN
          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"
  "/v1/recalls/years":
    get:
      summary: List available recall years
      tags:
      - Recalls
      description: Returns a list of distinct years for which recall data is available,
        ordered most recent first.
      operationId: getRecallYears
      security:
      - bearer_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
                example:
                - 2024
                - 2023
                - 2022
                description: Array of years in descending order
        '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
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/v1/recalls/makes/{year}":
    get:
      summary: List available recall makes for a year
      tags:
      - Recalls
      description: Returns a list of distinct vehicle makes for which recall data
        is available for the specified year.
      operationId: getRecallMakesByYear
      security:
      - bearer_auth: []
      parameters:
      - name: year
        in: path
        description: Model year (e.g., 2023)
        required: true
        example: 2023
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                - Ford
                - Honda
                - Toyota
                description: Array of make names in alphabetical order
        '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
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/v1/recalls/models/{year}/{make}":
    get:
      summary: List recall models for a year and make
      tags:
      - Recalls
      description: Returns a list of distinct model names for which recall data is
        available for the given year and make.
      operationId: getRecallModelsByYearMake
      security:
      - bearer_auth: []
      parameters:
      - name: year
        in: path
        description: Model year (e.g., 2024)
        required: true
        example: 2024
        schema:
          type: integer
      - name: make
        in: path
        description: Vehicle manufacturer name (e.g., Toyota)
        required: true
        example: Toyota
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                - Camry
                - Corolla
                - RAV4
                description: Array of model names in alphabetical order
        '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
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/v1/recalls/{year}/{make}/{model}":
    get:
      summary: Get recalls for a vehicle
      tags:
      - Recalls
      description: Returns a list of recalls for the specified vehicle. Each recall
        includes details such as the recall ID, summary, consequence, remedy, and
        the date it was issued.
      operationId: getRecallsByVehicle
      security:
      - bearer_auth: []
      parameters:
      - name: year
        in: path
        description: Model year (e.g., 2024)
        required: true
        example: 2024
        schema:
          type: integer
      - name: make
        in: path
        description: Vehicle manufacturer name (e.g., Toyota)
        required: true
        example: Toyota
        schema:
          type: string
      - name: model
        in: path
        description: Vehicle model name (e.g., Camry)
        required: true
        example: Camry
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/recall"
                description: Array of recall objects for the specified vehicle
        '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
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/v1/safety-ratings/years":
    get:
      summary: List available safety rating years
      tags:
      - Safety Ratings
      description: Returns a list of distinct years for which safety rating data is
        available, ordered most recent first.
      operationId: getSafetyRatingYears
      security:
      - bearer_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
                example:
                - 2024
                - 2023
                - 2022
                description: Array of years in descending order
        '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
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/v1/safety-ratings/makes/{year}":
    get:
      summary: List available safety rating makes for a year
      tags:
      - Safety Ratings
      description: Returns a list of distinct vehicle makes for which safety rating
        data is available for the specified year.
      operationId: getSafetyRatingMakesByYear
      security:
      - bearer_auth: []
      parameters:
      - name: year
        in: path
        description: Model year (e.g., 2024)
        required: true
        example: 2024
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                - Ford
                - Honda
                - Toyota
                description: Array of make names in alphabetical order
        '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
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/v1/safety-ratings/models/{year}/{make}":
    get:
      summary: List safety rating models for a year and make
      tags:
      - Safety Ratings
      description: Returns a list of distinct model names for which safety rating
        data is available for the given year and make.
      operationId: getSafetyRatingModelsByYearMake
      security:
      - bearer_auth: []
      parameters:
      - name: year
        in: path
        description: Model year (e.g., 2024)
        required: true
        example: 2024
        schema:
          type: integer
      - name: make
        in: path
        description: Vehicle manufacturer name (e.g., Toyota)
        required: true
        example: Toyota
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                - Camry
                - Corolla
                - RAV4
                description: Array of model names in alphabetical order
        '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
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/v1/safety-ratings/{year}/{make}/{model}":
    get:
      summary: Get safety ratings for a vehicle
      tags:
      - Safety Ratings
      description: Returns a list of NHTSA safety ratings for the specified vehicle.
        Each rating includes crash test star ratings and safety equipment details.
        Multiple results may be returned for different body styles or drive trains.
        Use the optional body_style and drive_train query parameters to narrow results.
      operationId: getSafetyRatingsByVehicle
      security:
      - bearer_auth: []
      parameters:
      - name: year
        in: path
        description: Model year (e.g., 2024)
        required: true
        example: 2024
        schema:
          type: integer
      - name: make
        in: path
        description: Vehicle manufacturer name (e.g., Toyota)
        required: true
        example: Toyota
        schema:
          type: string
      - name: model
        in: path
        description: Vehicle model name (e.g., Camry)
        required: true
        example: Camry
        schema:
          type: string
      - name: body_style
        in: query
        description: Filter by body style (e.g., '4 DR Sedan')
        required: false
        schema:
          type: string
      - name: drive_train
        in: query
        description: Filter by drive train (e.g., 'FWD', 'AWD')
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/safety_rating"
                description: Array of safety rating objects for the specified vehicle
        '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
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/v1/specs/search":
    get:
      summary: Search and rank vehicles by metric
      tags:
      - Vehicle Specifications
      description: Search and rank vehicles by a performance or efficiency metric.
        Supports filtering by year, make, model, body type, fuel type, drive type,
        and transmission. For electrified vehicles, horsepower and torque use total
        system output when available. Fuel economy supports combined values from all
        available test cycles and MPGe for EVs. Requires credit access; charged at
        the published vehicle search rate.
      operationId: searchVehicles
      security:
      - bearer_auth: []
      parameters:
      - name: metric
        in: query
        required: true
        schema:
          type: string
          enum:
          - horsepower
          - torque
          - mpg
          - acceleration
          - max_speed
          - curb_weight
          - cargo
        description: Metric to rank by
        example: horsepower
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
        description: Sort order. Defaults to desc for horsepower/torque/mpg/max_speed/cargo,
          asc for acceleration/curb_weight
        example: desc
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 25
        description: Number of results (default 10, max 25)
        example: 10
      - name: year
        in: query
        required: false
        schema:
          type: integer
        description: Filter by an exact confirmed production year. A missing final
          production year is not assumed to mean ongoing production.
        example: 2023
      - name: year_min
        in: query
        required: false
        schema:
          type: integer
        description: Minimum confirmed production year (inclusive)
        example: 2020
      - name: year_max
        in: query
        required: false
        schema:
          type: integer
        description: Maximum confirmed production year (inclusive)
        example: 2024
      - name: make
        in: query
        required: false
        schema:
          type: string
        description: Filter by manufacturer (case-insensitive)
        example: Toyota
      - name: model
        in: query
        required: false
        schema:
          type: string
        description: Filter by model name (case-insensitive)
        example: Camry
      - name: body_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - sedan
          - hatchback
          - liftback
          - coupe
          - cabriolet
          - roadster
          - targa
          - suv
          - crossover
          - station_wagon
          - pickup
          - van
          - minivan
          - minibus
          - offroad
          - quadricycle
        description: Filter by body type (e.g. 'sedan', 'suv', 'hatchback'). Matches
          vehicles where body_type is the given value or an array containing it (e.g.
          filtering 'suv' matches both ['suv'] and ['suv', 'crossover']).
        example: sedan
      - name: fuel_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - petrol
          - diesel
          - electric
          - natural_gas
          - lpg
          - hydrogen
          - ethanol
          - ethanol_e85
          - ethanol_e100
          - synthetic_gasoline
          - mixture_of_two_stroke_engine
        description: Filter by fuel type — matches vehicles whose fuel_type array
          contains the value (e.g. 'petrol', 'diesel', 'electric', 'ethanol_e85')
        example: petrol
      - name: drive_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - fwd
          - rwd
          - awd
          - unknown
        description: Filter by drive type (e.g. 'fwd', 'rwd', 'awd')
        example: awd
      - name: transmission
        in: query
        required: false
        schema:
          type: string
          enum:
          - at
          - mt
          - dct
          - cvt
          - amt
          - imt
          - unknown
        description: Filter by transmission type. Electric vehicles generally have
          no transmission value; use fuel_type=electric to find them.
        example: at
      responses:
        '200':
          description: successful search
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/search_results_response"
        '400':
          description: invalid metric
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '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"
  "/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"
  "/v1/specs/years":
    get:
      summary: List all available years
      tags:
      - Vehicle Specifications
      description: Returns a list of all available vehicle model years in descending
        order.
      operationId: getYears
      security:
      - bearer_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
                example:
                - 2024
                - 2023
                - 2022
                - 2021
                - 2020
                description: Array of years in descending order
        '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"
servers:
- url: https://api.carstat.app
  description: Production server
components:
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: API Token
      description: API token authentication. Get your token from the dashboard.
  schemas:
    year:
      type: integer
      description: Vehicle model year
      example: 2024
    make:
      type: string
      description: Vehicle manufacturer name
      example: Toyota
    model:
      type: string
      description: Vehicle model name
      example: Camry
    engine:
      type: string
      description: Engine/powertrain configuration
      example: 2.0 (173 Hp) Direct Shift CVT
    recall:
      type: object
      properties:
        rcdate:
          type: string
          description: Recall date
          example: '2024-01-15'
        campno:
          type: string
          description: Campaign number
          example: 24V123000
        mfgname:
          type: string
          description: Manufacturer name
          example: Toyota
        compname:
          type: string
          description: Component name
          example: Air Bags
        desc_defect:
          type: string
          description: Defect description
        consequence_defect:
          type: string
          description: Consequence of defect
        corrective_action:
          type: string
          description: Corrective action
    safety_rating:
      type: object
      description: NHTSA safety rating for a vehicle variant. Star ratings are numbers.
        The data object contains full test results, safety equipment, and additional
        details.
      properties:
        id:
          type: integer
          description: Safety rating record ID
        make:
          type: string
          description: Vehicle manufacturer
          example: Toyota
        model:
          type: string
          description: Vehicle model
          example: Camry
        year_int:
          type: integer
          description: Model year
          example: 2024
        body_style:
          type: string
          description: Body style
          example: 4 DR Sedan
        vehicle_type:
          type: string
          description: Vehicle type
          example: Passenger Car
        drive_train:
          type: string
          description: Drive train
          example: FWD
        overall_stars:
          type: number
          description: Overall star rating
          example: 5.0
        overall_frnt_stars:
          type: number
          description: Overall frontal star rating
          example: 4.0
        overall_side_stars:
          type: number
          description: Overall side star rating
          example: 5.0
        side_pole_stars:
          type: number
          description: Side pole star rating
          example: 5.0
        rollover_stars:
          type: number
          description: Rollover star rating
          example: 4.0
        frnt_driv_stars:
          type: number
          description: Frontal driver star rating
        frnt_pass_stars:
          type: number
          description: Frontal passenger star rating
        side_driv_stars:
          type: number
          description: Side driver star rating
        side_pass_stars:
          type: number
          description: Side passenger star rating
        side_barrier_star:
          type: number
          description: Side barrier star rating
        comb_frnt_star:
          type: number
          description: Combined front star rating
        comb_rear_star:
          type: number
          description: Combined rear star rating
        data:
          type: object
          description: Full NHTSA safety data including test results, equipment details,
            and additional ratings
    vin_specs_response:
      type: object
      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
          nullable: true
          description: Manufacturer decoded from the VIN
        model:
          type: string
          nullable: true
          description: Model decoded from the VIN, normalised to the name used in
            the catalog. Some manufacturers encode a specific trim where the catalog
            lists the wider model line; this field is then the model line the specifications
            were found under, and the trim is available from the VIN decoding endpoint.
            Null when the VIN identifies the manufacturer but not a specific model.
        year:
          type: integer
          nullable: true
          description: Model year decoded from VIN position 10
        match_confidence:
          type: string
          enum:
          - exact
          - narrowed
          - ambiguous
          description: 'How precisely the VIN resolved to a single trim: ''exact''
            (one candidate remains), ''narrowed'' (reduced but several remain), or
            ''ambiguous'' (the VIN does not distinguish the remaining trims). A successful
            response always contains at least one candidate; when none can be found
            the endpoint returns 404. A VIN cannot encode trim/options for most makes,
            so a single result is not guaranteed.'
        matched_on:
          type: array
          items:
            type: string
          description: Decoded signals that discriminated between trims, e.g. engine_code,
            cylinders, displacement, fuel, body, drive_type.
        best_match:
          type: object
          nullable: true
          description: The single most likely modification specification for the VIN
            (top-ranked candidate).
        candidates:
          type: array
          items:
            type: object
          description: Matching modification specifications, narrowed to the trims
            consistent with the decoded VIN.
      required:
      - vin
      - errors
      - make
      - model
      - year
      - candidates
      - match_confidence
      - matched_on
      - best_match
    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
          nullable: true
          description: Manufacturer decoded from the VIN
        model:
          type: string
          nullable: true
          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
          nullable: true
          description: Model year decoded from VIN position 10
        wmi:
          type: string
          nullable: true
          description: World Manufacturer Identifier (VIN positions 1-3).
        manufacturer:
          type: string
          nullable: true
          description: Registered manufacturer name, e.g. "TESLA, INC." — distinct
            from the vehicle make/brand.
        region:
          type: string
          nullable: true
          description: Geographic region of manufacture, e.g. "ASIA", "NORTH AMERICA",
            "EUROPE".
        country:
          type: string
          nullable: true
          description: Manufacturing country decoded from the VIN/WMI.
        vehicle_type:
          type: string
          nullable: true
          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
          nullable: true
          description: Vehicle series / sub-model as decoded from the VIN.
        trim:
          type: string
          nullable: true
          description: Trim level as decoded from the VIN.
        engine_manufacturer:
          type: string
          nullable: true
          description: Company that built the engine, which is not always the vehicle's
            make. Not available for all manufacturers.
        check_digit:
          type: object
          nullable: true
          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
              nullable: true
              description: Check digit character present in the supplied VIN (VIN
                position 9).
            expected:
              type: string
              nullable: true
              description: Check digit character the rest of the VIN implies.
            is_valid:
              type: boolean
              nullable: true
              description: Whether the supplied check digit matches the expected one.
        plant:
          type: object
          nullable: true
          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
              nullable: true
              description: Plant country.
            city:
              type: string
              nullable: true
              description: Plant city.
            state:
              type: string
              nullable: true
              description: Plant state or province. Not available for all plants.
            code:
              type: string
              nullable: true
              description: Plant code (VIN position 11).
            manufacturer:
              type: string
              nullable: true
              description: Plant operator/manufacturer.
      required:
      - vin
      - errors
      - make
      - model
      - year
      - wmi
      - manufacturer
      - region
      - country
      - vehicle_type
      - series
      - trim
      - engine_manufacturer
      - check_digit
      - plant
    vehicle_specs_response:
      type: object
      description: Vehicle modification specification. All spec groups are always
        present; fields with no data are null. See GET /v1/specs/schema for the full
        typed JSON Schema.
      properties:
        powertrain_architecture:
          type: object
          nullable: true
          description: 'Boolean flags: bev, fcev, phev, mhev, hev, ice'
        fuel_consumption:
          type: object
          nullable: true
          description: Nested consumption values keyed by cycle (combined, city, highway,
            …)
        identity:
          type: object
          description: make, model, generation, display_name, year_start, year_end,
            body_type, seating_capacity_min/max, number_of_doors, modification_id
        performance:
          type: object
          description: acceleration_0_to_100_kmh, max_speed, weight_to_power_ratio,
            weight_to_torque_ratio
        engine:
          type: object
          description: fuel_type, horsepower, torque, displacement, cylinders, aspiration,
            oil, valvetrain, …
        electric_system:
          type: object
          description: battery capacity/voltage/technology/location, electric range,
            motors, charging_system, …
        drivetrain:
          type: object
          description: drivetrain_layout, drive_type, gears, transmission
        dimensions:
          type: object
          description: length, width, height, wheelbase, tracks, overhangs, ground_clearance,
            drag_coefficient, …
        weight_and_capacities:
          type: object
          description: curb_weight, fuel_tank_capacity, trunk_capacity, towing loads,
            …
        chassis:
          type: object
          description: suspension, front_brakes, rear_brakes, assisting_systems, steering,
            tires_size, …
    search_result_item:
      type: object
      description: A single vehicle result from the search endpoint
      properties:
        modification_id:
          type: string
          format: uuid
          description: Unique modification identifier
        name:
          type: string
          description: Engine/powertrain configuration name
        year_start:
          type: integer
          description: First model year this configuration was available
        year_end:
          type: integer
          nullable: true
          description: Last confirmed production year; null when no final year is
            available
        make:
          type: string
          description: Manufacturer name
        model:
          type: string
          description: Model name
        generation:
          type: string
          nullable: true
          description: Vehicle generation name
        model_year:
          type: integer
          deprecated: true
          description: Deprecated compatibility alias for year_start
        body_type:
          type: string
          nullable: true
          description: Body type(s), comma-separated when multiple (e.g. 'sedan',
            'suv, crossover')
      additionalProperties: true
    search_results_response:
      type: object
      properties:
        metric:
          type: string
          description: |-
            The metric used for ranking. Available metrics and their data sources:
            - `horsepower` — total system power (hp) for electrified vehicles; engine hp for ICE; summed motor output when no aggregate is available. Default order: desc.
            - `torque` — total system torque (Nm) for electrified vehicles; engine torque for ICE; summed motor output when no aggregate is available. Default order: desc.
            - `mpg` — combined US mpg from the available test cycle (combined, WLTC, EPA, CLTC, NEDC-equivalent, or NEDC); falls back to extra-urban mpg or EV MPGe. Default order: desc.
            - `acceleration` — 0–100 km/h time in seconds. Default order: asc (faster = lower).
            - `max_speed` — top speed in km/h. Default order: desc.
            - `curb_weight` — kerb weight in kg. Default order: asc (lighter = lower).
            - `cargo` — maximum trunk/boot volume in litres. Default order: desc.
          enum:
          - horsepower
          - torque
          - mpg
          - acceleration
          - max_speed
          - curb_weight
          - cargo
          example: horsepower
        order:
          type: string
          enum:
          - asc
          - desc
          description: Sort order applied
        total_matching:
          type: integer
          description: Total vehicles matching the filters (before limit)
        showing:
          type: integer
          description: Number of results returned
        results:
          type: array
          items:
            "$ref": "#/components/schemas/search_result_item"
      required:
      - metric
      - order
      - total_matching
      - showing
      - results
    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_no_specs_error:
      type: object
      description: Returned by GET /v1/specs/vin/{vin} when the VIN was read successfully
        but no published specifications match the vehicle it identifies.
      properties:
        error:
          type: string
          description: Error message
        decode_available_at:
          type: string
          description: Path to the VIN decoding endpoint for this VIN. The VIN itself
            is valid and readable, so the vehicle it identifies can still be returned
            there — useful for vehicle classes this specification catalog does not
            cover, such as motorcycles, trailers and buses. Requires credit access;
            charged at the published VIN decoding rate.
      required:
      - error
      - decode_available_at
security:
- bearer_auth: []