carstat-app Vehicle Specifications API

openapi: 3.2.0
info:
  title: REST API Reference Vehicle Specifications 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: 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.
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/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/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'
components:
  schemas:
    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
          - 'null'
          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
          - 'null'
          description: Vehicle generation name
        model_year:
          type: integer
          deprecated: true
          description: Deprecated compatibility alias for year_start
        body_type:
          type:
          - string
          - 'null'
          description: Body type(s), comma-separated when multiple (e.g. 'sedan', 'suv, crossover')
      additionalProperties: true
    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
          - '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. 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
          - 'null'
          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
          - 'null'
          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
    error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
      - error
    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
    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
          - 'null'
          description: 'Boolean flags: bev, fcev, phev, mhev, hev, ice'
        fuel_consumption:
          type:
          - object
          - 'null'
          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, …
    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
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: API Token
      description: API token authentication. Get your token from the dashboard.