Vehicles.dev Vehicles API

openapi: 3.2.0
info:
  description: 'Vehicle identity and intelligence data — VIN decode, market value, listings, depreciation, reports, listing history, photos, specifications, recalls, and ownership costs — plus the account, API-key, and billing control plane. Data endpoints authenticate with a product API key (`Authorization: Bearer <key>`); control-plane endpoints use a dashboard session token. Errors are RFC 9457 application/problem+json, and every response carries an x-request-id header.'
  title: .dev Vehicles API
  version: 0.0.0
servers:
- description: Vehicles.dev API
  url: https://api.vehicles.dev
tags:
- name: Vehicles
paths:
  /v1/vehicles/vin/{vin}:
    get:
      operationId: getVehicleVinDecode
      tags:
      - Vehicles
      parameters:
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: path
        name: vin
        required: true
      security:
      - apiKeyBearer: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - origin
                - source
                - vehicle
                - vin
                properties:
                  origin:
                    anyOf:
                    - type: string
                      enum:
                      - store
                    - type: string
                      enum:
                      - vpic
                  source:
                    type: string
                    enum:
                    - carscrape
                  vehicle:
                    type: object
                    properties: {}
                    additionalProperties: true
                  vin:
                    type: string
                additionalProperties: false
        '400':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '401':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '402':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '403':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '404':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '409':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '429':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '500':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '503':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
  /v1/vehicles/market-value:
    get:
      operationId: getVehicleMarketValue
      tags:
      - Vehicles
      parameters:
      - schema:
          type: integer
          minimum: 0
        in: query
        name: base_msrp
        required: false
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: query
        name: body_style
        required: false
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: query
        name: color
        required: false
      - schema:
          type: string
          maxLength: 16
          minLength: 1
        in: query
        name: condition
        required: false
      - schema:
          type: string
          maxLength: 16
          minLength: 1
        in: query
        name: drivetrain
        required: false
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: query
        name: fuel
        required: false
      - schema:
          type: string
          maxLength: 64
          minLength: 1
        in: query
        name: make
        required: true
      - schema:
          type: integer
          minimum: 0
        in: query
        name: miles
        required: false
      - schema:
          type: string
          maxLength: 64
          minLength: 1
        in: query
        name: model
        required: true
      - schema:
          type: string
          maxLength: 2
          minLength: 2
        in: query
        name: state
        required: false
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: query
        name: transmission
        required: false
      - schema:
          type: string
          maxLength: 64
          minLength: 1
        in: query
        name: trim
        required: false
      - schema:
          type: integer
          maximum: 2100
          minimum: 1900
        in: query
        name: year
        required: true
      security:
      - apiKeyBearer: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - currency
                - estimateUsd
                - inputs
                - medianApePct
                - source
                properties:
                  currency:
                    type: string
                  estimateUsd:
                    type: integer
                  inputs:
                    type: object
                    properties: {}
                    additionalProperties: true
                  medianApePct:
                    type: number
                  source:
                    type: string
                    enum:
                    - carscrape
                additionalProperties: false
        '400':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '401':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '402':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '403':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '404':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '409':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '429':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '500':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '503':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
  /v1/vehicles/listings:
    get:
      operationId: getVehicleListings
      tags:
      - Vehicles
      parameters:
      - schema:
          type: boolean
        in: query
        name: active
        required: false
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: query
        name: condition
        required: false
      - schema:
          type: integer
          maximum: 500
          minimum: 1
        in: query
        name: limit
        required: false
      - schema:
          type: string
          maxLength: 64
          minLength: 1
        in: query
        name: make
        required: false
      - schema:
          type: integer
          minimum: 0
        in: query
        name: mileage_max
        required: false
      - schema:
          type: number
          maximum: 1
          minimum: 0
        in: query
        name: min_quality
        required: false
      - schema:
          type: string
          maxLength: 64
          minLength: 1
        in: query
        name: model
        required: false
      - schema:
          type: integer
          minimum: 0
        in: query
        name: offset
        required: false
      - schema:
          anyOf:
          - type: string
            enum:
            - asc
          - type: string
            enum:
            - desc
        in: query
        name: order
        required: false
      - schema:
          type: integer
          minimum: 0
        in: query
        name: price_max
        required: false
      - schema:
          type: integer
          minimum: 0
        in: query
        name: price_min
        required: false
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: query
        name: seller_type
        required: false
      - schema:
          type: boolean
        in: query
        name: sold
        required: false
      - schema:
          anyOf:
          - type: string
            enum:
            - price
          - type: string
            enum:
            - miles
          - type: string
            enum:
            - year
          - type: string
            enum:
            - days_on_market
        in: query
        name: sort
        required: false
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: query
        name: source
        required: false
      - schema:
          type: string
          maxLength: 2
          minLength: 2
        in: query
        name: state
        required: false
      - schema:
          type: boolean
        in: query
        name: valid_vin
        required: false
      - schema:
          type: integer
          maximum: 2100
          minimum: 1900
        in: query
        name: year_max
        required: false
      - schema:
          type: integer
          maximum: 2100
          minimum: 1900
        in: query
        name: year_min
        required: false
      security:
      - apiKeyBearer: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - count
                - limit
                - offset
                - results
                - source
                - total
                properties:
                  count:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object
                      properties: {}
                      additionalProperties: true
                  source:
                    type: string
                    enum:
                    - carscrape
                  total:
                    type: integer
                additionalProperties: false
        '400':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '401':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '402':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '403':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '404':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '409':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '429':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '500':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '503':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
  /v1/vehicles/depreciation:
    get:
      operationId: getVehicleDepreciation
      tags:
      - Vehicles
      parameters:
      - schema:
          type: string
          maxLength: 64
          minLength: 1
        in: query
        name: make
        required: true
      - schema:
          type: string
          maxLength: 64
          minLength: 1
        in: query
        name: model
        required: true
      security:
      - apiKeyBearer: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - annualDecay
                - byModelYear
                - curveByAge
                - make
                - model
                - source
                properties:
                  annualDecay:
                    anyOf:
                    - type: number
                    - type: 'null'
                  byModelYear:
                    type: array
                    items:
                      type: object
                      properties: {}
                      additionalProperties: true
                  curveByAge:
                    anyOf:
                    - type: array
                      items:
                        type: object
                        properties: {}
                        additionalProperties: true
                    - type: 'null'
                  make:
                    type: string
                  model:
                    type: string
                  source:
                    type: string
                    enum:
                    - carscrape
                additionalProperties: false
        '400':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '401':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '402':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '403':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '404':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '409':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '429':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '500':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '503':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
  /v1/vehicles/report/{vin}:
    get:
      operationId: getVehicleReport
      tags:
      - Vehicles
      parameters:
      - schema:
          type: integer
          minimum: 0
        in: query
        name: miles
        required: false
      - schema:
          type: string
          maxLength: 2
          minLength: 2
        in: query
        name: state
        required: false
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: path
        name: vin
        required: true
      security:
      - apiKeyBearer: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - coverage
                - depreciation
                - generatedAt
                - identity
                - marketValue
                - origin
                - source
                - vin
                properties:
                  coverage:
                    type: array
                    items:
                      type: string
                  depreciation:
                    anyOf:
                    - type: object
                      properties: {}
                      additionalProperties: true
                    - type: 'null'
                  generatedAt:
                    type: string
                  identity:
                    type: object
                    properties: {}
                    additionalProperties: true
                  marketValue:
                    anyOf:
                    - type: object
                      properties: {}
                      additionalProperties: true
                    - type: 'null'
                  origin:
                    anyOf:
                    - type: string
                      enum:
                      - store
                    - type: string
                      enum:
                      - vpic
                  source:
                    type: string
                    enum:
                    - carscrape
                  vin:
                    type: string
                additionalProperties: false
        '400':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '401':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '402':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '403':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '404':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '409':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '429':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '500':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '503':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
  /v1/vehicles/history/{vin}:
    get:
      operationId: getVehicleHistory
      tags:
      - Vehicles
      parameters:
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: path
        name: vin
        required: true
      security:
      - apiKeyBearer: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - currentPrice
                - currentlyActive
                - firstSeen
                - lastSeen
                - observations
                - priceChanges
                - priceMax
                - priceMin
                - source
                - vin
                properties:
                  currentPrice:
                    anyOf:
                    - type: integer
                    - type: 'null'
                  currentlyActive:
                    type: boolean
                  firstSeen:
                    type: string
                  lastSeen:
                    type: string
                  observations:
                    type: array
                    items:
                      type: object
                      properties: {}
                      additionalProperties: true
                  priceChanges:
                    type: integer
                  priceMax:
                    anyOf:
                    - type: integer
                    - type: 'null'
                  priceMin:
                    anyOf:
                    - type: integer
                    - type: 'null'
                  source:
                    type: string
                    enum:
                    - carscrape
                  vin:
                    type: string
                additionalProperties: false
        '400':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '401':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '402':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '403':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '404':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '409':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '429':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '500':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '503':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
  /v1/vehicles/photos/{vin}:
    get:
      operationId: getVehiclePhotos
      tags:
      - Vehicles
      parameters:
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: path
        name: vin
        required: true
      security:
      - apiKeyBearer: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - listingSource
                - listingUrl
                - photoCount
                - primaryImage
                - source
                - vin
                properties:
                  listingSource:
                    anyOf:
                    - type: string
                    - type: 'null'
                  listingUrl:
                    anyOf:
                    - type: string
                    - type: 'null'
                  photoCount:
                    anyOf:
                    - type: integer
                    - type: 'null'
                  primaryImage:
                    type: string
                  source:
                    type: string
                    enum:
                    - carscrape
                  vin:
                    type: string
                additionalProperties: false
        '400':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '401':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '402':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '403':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '404':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '409':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '429':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '500':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '503':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
  /v1/vehicles/specifications/{vin}:
    get:
      operationId: getVehicleSpecifications
      tags:
      - Vehicles
      parameters:
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: path
        name: vin
        required: true
      security:
      - apiKeyBearer: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - source
                - specifications
                - vin
                properties:
                  source:
                    type: string
                    enum:
                    - carscrape
                  specifications:
                    type: object
                    properties: {}
                    additionalProperties: true
                  vin:
                    type: string
                additionalProperties: false
        '400':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '401':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '402':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '403':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '404':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '409':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '429':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '500':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '503':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
  /v1/vehicles/recalls/{vin}:
    get:
      operationId: getVehicleRecalls
      tags:
      - Vehicles
      parameters:
      - schema:
          type: string
          maxLength: 32
          minLength: 1
        in: path
        name: vin
        required: true
      security:
      - apiKeyBearer: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - count
                - make
                - model
                - recalls
                - source
                - vin
                - year
                properties:
                  count:
                    type: integer
                  make:
                    type: string
                  model:
                    type: string
                  recalls:
                    type: array
                    items:
                      type: object
                      properties: {}
                      additionalProperties: true
                  source:
                    type: string
                    enum:
                    - carscrape
                  vin:
                    type: string
                  year:
                    type: integer
                additionalProperties: false
        '400':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '401':
          description: RFC 9457 problem details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/def-0'
        '4

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vehicles-dev-api/refs/heads/main/openapi/vehicles-dev-api-vehicles-api-openapi.yml