openapi: 3.0.3
info:
  title: VinAudit Data APIs
  version: "1.0.0"
  description: |
    Automotive Data & APIs. Access vehicle specifications, history reports, images,
    valuations, market listings, and automotive market insights through powerful APIs.

    All requests are authenticated with your VinAudit API key passed as the `key`
    query parameter. Each API is served from its own host (see the `servers` entry on
    each path). Full documentation: https://data.vinaudit.com/docs
  termsOfService: https://data.vinaudit.com/terms
  contact:
    name: VinAudit Data Support
    url: https://data.vinaudit.com/support
  x-logo:
    url: https://data.vinaudit.com/favicon-96x96.png
externalDocs:
  description: VinAudit Data API documentation
  url: https://data.vinaudit.com/docs

servers:
  - url: https://api.vinaudit.com

tags:
  - name: Market Data
    description: Market listings and market values for the US and Canada.
  - name: VIN Data
    description: VIN decoding, vehicle history, plate to VIN, and ownership cost.
  - name: Images
    description: Rendered vehicle images and background removal.

security:
  - apiKey: []

paths:
  # ---------------------------------------------------------------- Market Data
  /v2/marketvalue:
    servers:
      - url: https://marketvalue.vinaudit.com
    get:
      tags: [Market Data]
      operationId: getMarketValue
      summary: Market Values API
      description: >
        Estimates retail, wholesale, and trade-in values for passenger vehicles in the
        US and Canada using comparable sales records. Submit either `vin` or `id`.
        Also accepts POST with the same parameters.
      externalDocs:
        url: https://data.vinaudit.com/docs/api/market/values
      parameters:
        - $ref: "#/components/parameters/vinOptional"
        - name: id
          in: query
          description: Year/make/model/trim ID as returned by the VIN Decoder selections function.
          schema: { type: string, example: 2014_toyota_corolla_s }
        - name: format
          in: query
          schema: { type: string, enum: [json, xml, html], default: json }
        - name: mileage
          in: query
          description: Numeric mileage or `average`. Defaults to average mileage.
          schema: { type: string, example: "90000" }
        - name: period
          in: query
          description: Days to look back for sales data (max 365).
          schema: { type: integer, maximum: 365, example: 90 }
        - name: type
          in: query
          schema: { type: string, enum: [retail, tradein], default: retail }
        - name: condition
          in: query
          schema: { type: string, enum: [average, like_new, not_great], default: average }
        - name: known_damage
          in: query
          schema:
            type: string
            enum: [frame_damage, airbags_deployed, salvage, brand, rollback, minor_damage, lemon, rental, prior_theft]
        - $ref: "#/components/parameters/country"
      responses:
        "200":
          description: Market value estimate
          content:
            application/json:
              schema: { $ref: "#/components/schemas/MarketValue" }
              example:
                vin: 2T1BURHE3EC020936
                success: true
                id: 2014_toyota_corolla_s
                vehicle: 2014 Toyota Corolla S
                mean: 10880.54
                stdev: 2400
                count: 271
                mileage: 130163
                certainty: 99
                period: ["2025-08-17", "2025-10-10"]
                prices: { above: 13281.53, average: 10880.54, below: 8479.55 }
                type: retail

  /v1/listings:
    servers:
      - url: https://marketlistings.vinaudit.com
    get:
      tags: [Market Data]
      operationId: searchMarketListings
      summary: Market Listings API
      description: >
        Search retail vehicle listings across the US and Canada with 20+ filters
        (dealer, location, radius, year/make/model/trim, vehicle attributes).
        Also accepts POST with the same parameters.
      externalDocs:
        url: https://data.vinaudit.com/docs/api/market/listings
      parameters:
        - name: format
          in: query
          schema: { type: string, enum: [json, xml], default: json }
        - $ref: "#/components/parameters/vinOptional"
        - name: vehicle_make
          in: query
          schema: { type: string, example: Tesla }
        - name: spec_vin
          in: query
          description: Reference VIN used to find listings with similar year/make/model.
          schema: { type: string }
        - name: spec_vin_match
          in: query
          schema: { type: string, enum: [model, trim] }
        - name: spec_id
          in: query
          description: >
            Year/make/model/trim ID (supports year, year_make, year_make_model,
            year_make_model_trim, make, make_model, make_model_trim). Takes precedence over `spec_vin`.
          schema: { type: string, example: 2021_tesla_model-3_long-range }
        - name: listing_type
          in: query
          description: New, Used, Certified (default all three).
          schema: { type: string, example: Used }
        - name: listing_price_min
          in: query
          schema: { type: number }
        - name: listing_price_max
          in: query
          schema: { type: number }
        - name: postal
          in: query
          schema: { type: string, example: "30680" }
        - name: latitude
          in: query
          schema: { type: number }
        - name: longitude
          in: query
          schema: { type: number }
        - name: radius
          in: query
          description: Miles (USA) or kilometers (Canada). Default 25.
          schema: { type: integer, default: 25 }
        - name: city
          in: query
          description: If set, `region` is required.
          schema: { type: string }
        - name: region
          in: query
          description: 2-letter state/province code.
          schema: { type: string, example: GA }
        - $ref: "#/components/parameters/country"
        - name: seller_type
          in: query
          description: Default franchise,independent.
          schema: { type: string, enum: [franchise, independent, private] }
        - name: seller_id
          in: query
          schema: { type: string, example: dealername_winder_ga }
        - name: dealer_attribution
          in: query
          schema: { type: integer }
        - name: spec_accuracy
          in: query
          schema: { type: integer }
        - name: listing_status
          in: query
          description: Comma-separated -- active, in-transit, dropped, all. Default active,in-transit.
          schema: { type: string }
        - name: history_days
          in: query
          description: Days to look back for dropped listings.
          schema: { type: integer, default: 30 }
        - name: vehicle_type
          in: query
          schema: { type: string, enum: [sedan, coupe, truck, suv, hatchback, van, wagon, convertible, minivan] }
        - name: vehicle_fuel_type
          in: query
          schema: { type: string, enum: [diesel, electric, flex, gasoline, hybrid, hydrogen, plug-in] }
        - name: vehicle_engine_cylinders
          in: query
          schema: { type: integer }
        - name: vehicle_transmission_type
          in: query
          schema: { type: string, enum: [automatic, manual] }
        - name: vehicle_drivetrain
          in: query
          schema: { type: string, enum: [rwd, fwd, awd, 4wd] }
        - name: vehicle_doors
          in: query
          schema: { type: integer }
        - name: page_size
          in: query
          schema: { type: integer, default: 100 }
        - name: page
          in: query
          schema: { type: integer, default: 1 }
      responses:
        "200":
          description: Paged list of listings
          content:
            application/json:
              schema:
                type: object
                properties:
                  total: { type: integer, description: Listings in this page }
                  query_total: { type: integer, description: Total matching listings }
                  page: { type: integer }
                  page_size: { type: integer }
                  listings:
                    type: array
                    items: { type: object, additionalProperties: true }

  # ---------------------------------------------------------------- VIN Data
  /v3/specifications:
    servers:
      - url: https://specifications.vinaudit.com
    get:
      tags: [VIN Data]
      operationId: getVehicleSpecifications
      summary: VIN Decoder API -- vehicle specifications
      description: >
        Get vehicle attributes, equipment, colors, recalls, warranties and photos by VIN,
        by year/make/model/trim, or by ID. Also accepts POST with the same parameters.
      externalDocs:
        url: https://data.vinaudit.com/docs/api/vin/decoder
      parameters:
        - $ref: "#/components/parameters/vinOptional"
        - name: year
          in: query
          schema: { type: integer, example: 2004 }
        - name: make
          in: query
          schema: { type: string, example: toyota }
        - name: model
          in: query
          schema: { type: string, example: corolla }
        - name: trim
          in: query
          schema: { type: string, example: ce }
        - name: id
          in: query
          description: year_make_model_trim or year_make_model_trim_style ID.
          schema: { type: string, example: 2013_bmw_3series_328i_sedan }
        - name: include
          in: query
          description: Comma-separated -- selections, attributes, equipment, colors, recalls, warranties, photos.
          schema: { type: string, example: "attributes,equipment" }
        - name: format
          in: query
          schema: { type: string, enum: [json, xml], default: json }
      responses:
        "200":
          description: Vehicle specifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  input: { type: object, additionalProperties: true }
                  selections: { type: object, additionalProperties: true }
                  attributes: { type: object, additionalProperties: true }
                  colors:
                    type: array
                    items:
                      type: object
                      properties:
                        category: { type: string }
                        name: { type: string }
                  equipment:
                    type: array
                    items:
                      type: object
                      properties:
                        group: { type: string }
                        name: { type: string }
                        availability: { type: string }
                  recalls:
                    type: array
                    items: { type: object, additionalProperties: true }
                  warranties:
                    type: array
                    items: { type: object, additionalProperties: true }
                  photos:
                    type: array
                    items: { type: object, additionalProperties: true }

  /v3/selections:
    servers:
      - url: https://specifications.vinaudit.com
    get:
      tags: [VIN Data]
      operationId: getVehicleSelections
      summary: VIN Decoder API -- vehicle selections
      description: >
        Get a standardized list of year, make, model, trim and style selections with
        names and IDs. Also accepts POST with the same parameters.
      externalDocs:
        url: https://data.vinaudit.com/docs/api/vin/decoder
      parameters:
        - name: list
          in: query
          description: >
            Attributes to include, joined with `+` -- e.g. year, year+make, year+make+model,
            year+make+model+trim, year+make+model+trim+style, make, make+model, make+model+trim,
            make+model+trim+style.
          schema: { type: string, example: make+model }
        - name: id
          in: query
          description: ID for any year/make/model/trim/style combination (e.g. 2013_subaru_outback).
          schema: { type: string, example: 2013_subaru }
        - name: year
          in: query
          schema: { type: integer, example: 2013 }
        - name: make
          in: query
          schema: { type: string, example: subaru }
        - name: model
          in: query
          schema: { type: string, example: outback }
        - name: trim
          in: query
          schema: { type: string, example: base }
        - name: style
          in: query
          schema: { type: string, example: wagon }
        - name: format
          in: query
          schema: { type: string, enum: [json, xml, csv], default: json }
        - name: collection
          in: query
          description: >
            in-market (YMMTs with 10+ active listings in the past 90 days), popular
            (1980+ from popular makes), or all.
          schema: { type: string, enum: [in-market, popular, all] }
      responses:
        "200":
          description: Selections tree (years > makes > models > trims > styles)
          content:
            application/json:
              schema:
                type: object
                properties:
                  selections:
                    type: object
                    properties:
                      years: { type: array, items: { $ref: "#/components/schemas/SelectionNode" } }
                      makes: { type: array, items: { $ref: "#/components/schemas/SelectionNode" } }
                  error: { type: string, example: invalid_parameters }
                  details: { type: string }

  /v1/licenselookup:
    servers:
      - url: https://plate2vin.vinaudit.com
    get:
      tags: [VIN Data]
      operationId: plateToVin
      summary: Plate to VIN API
      description: Convert a US license plate and state into a VIN.
      externalDocs:
        url: https://data.vinaudit.com/docs/api/vin/plate-vin
      parameters:
        - name: plate
          in: query
          required: true
          schema: { type: string, example: GHQ3084 }
        - name: state
          in: query
          required: true
          description: Two-letter state abbreviation.
          schema: { type: string, example: OH }
        - name: format
          in: query
          schema: { type: string, enum: [json, xml], default: json }
      responses:
        "200":
          description: Lookup result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  vin: { type: string }
                  error:
                    type: string
                    description: invalid_input, invalid_key, no_data, or blank.
              example: { success: true, vin: 1C6SRFJT2NN300571 }

  /v2/query:
    get:
      tags: [VIN Data]
      operationId: queryVin
      summary: Vehicle History API -- query a VIN for records
      description: >
        Decode a VIN (model years 1981+) and get a report ID to reuse with /v2/pullreport
        and /v2/report. Requires an API bulk access account.
      externalDocs:
        url: https://data.vinaudit.com/docs/api/vin/vehicle-history
      parameters:
        - $ref: "#/components/parameters/vinRequired"
        - $ref: "#/components/parameters/user"
        - $ref: "#/components/parameters/pass"
        - $ref: "#/components/parameters/historyFormat"
        - $ref: "#/components/parameters/skipspec"
        - $ref: "#/components/parameters/mode"
        - $ref: "#/components/parameters/callback"
      responses:
        "200":
          description: VIN query result
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string, description: Report ID to reuse with /v2/pullreport or /v2/report }
                  vin: { type: string }
                  attributes: { type: object, additionalProperties: true }
                  success: { type: boolean }
                  error: { type: string }
                  error_message: { type: string }
              example:
                vin: 1VXBR12EXCP901214
                id: S41149125266
                attributes:
                  year: "2005"
                  make: TOYOTA
                  model: COROLLA CE
                  style: SEDAN (4-Door)
                success: true
                error: ""

  /v2/pullreport:
    get:
      tags: [VIN Data]
      operationId: pullVehicleHistoryReport
      summary: Vehicle History API -- generate a vehicle history report
      description: >
        Generate a vehicle history report for a VIN. Reports are retained for 90 days --
        reuse the same `id` with the same VIN to retrieve the same report without a new
        billable lookup. Also accepts POST with the same parameters.
      externalDocs:
        url: https://data.vinaudit.com/docs/api/vin/vehicle-history
      parameters:
        - name: id
          in: query
          required: true
          description: Unique report/request ID. Reuse it for the same VIN within 90 days.
          schema: { type: string, example: "00000000000002" }
        - $ref: "#/components/parameters/vinRequired"
        - $ref: "#/components/parameters/user"
        - $ref: "#/components/parameters/pass"
        - $ref: "#/components/parameters/reportFormat"
        - $ref: "#/components/parameters/mode"
        - $ref: "#/components/parameters/reportType"
        - $ref: "#/components/parameters/brand"
        - $ref: "#/components/parameters/lang"
        - $ref: "#/components/parameters/callback"
      responses:
        "200":
          $ref: "#/components/responses/VehicleHistoryReport"

  /v2/report:
    get:
      tags: [VIN Data]
      operationId: getVehicleHistoryReport
      summary: Vehicle History API -- view a generated report
      description: >
        Retrieve a previously generated vehicle history report by report ID within the
        90-day retention period. Also accepts POST with the same parameters.
      externalDocs:
        url: https://data.vinaudit.com/docs/api/vin/vehicle-history
      parameters:
        - name: id
          in: query
          required: true
          description: The report ID.
          schema: { type: string, example: "182896361699" }
        - $ref: "#/components/parameters/reportFormat"
        - $ref: "#/components/parameters/reportType"
        - $ref: "#/components/parameters/brand"
        - $ref: "#/components/parameters/lang"
        - $ref: "#/components/parameters/skipspec"
        - $ref: "#/components/parameters/mode"
        - $ref: "#/components/parameters/callback"
      responses:
        "200":
          $ref: "#/components/responses/VehicleHistoryReport"

  /getownershipcost.php:
    servers:
      - url: https://ownershipcost.vinaudit.com
    get:
      tags: [VIN Data]
      operationId: getOwnershipCost
      summary: Vehicle Ownership Cost API
      description: >
        Estimate 5-year ownership costs by VIN, including depreciation, insurance, fuel,
        maintenance, repairs, and state taxes/fees.
      externalDocs:
        url: https://data.vinaudit.com/docs/api/vin/vehicle-ownership
      parameters:
        - $ref: "#/components/parameters/vinRequired"
        - name: state
          in: query
          required: true
          description: Two-letter state code.
          schema: { type: string, example: WA }
        - name: format
          in: query
          schema: { type: string, enum: [json, xml], default: json }
      responses:
        "200":
          description: 5-year ownership cost estimate (each array = years 1-5)
          content:
            application/json:
              schema:
                type: object
                properties:
                  vin: { type: string }
                  mileage_start: { type: integer, description: Current mileage (default -1) }
                  mileage_year: { type: integer, description: Estimated yearly mileage (default 15000) }
                  vehicle: { type: string }
                  trim: { type: string }
                  depreciation_cost: { $ref: "#/components/schemas/FiveYearCost" }
                  insurance_cost: { $ref: "#/components/schemas/FiveYearCost" }
                  fuel_cost: { $ref: "#/components/schemas/FiveYearCost" }
                  maintenance_cost: { $ref: "#/components/schemas/FiveYearCost" }
                  repairs_cost: { $ref: "#/components/schemas/FiveYearCost" }
                  fees_cost: { $ref: "#/components/schemas/FiveYearCost" }
                  total_cost: { $ref: "#/components/schemas/FiveYearCost" }
                  total_cost_sum: { type: number }
              example:
                vin: 1NXBR32E85Z505904
                mileage_start: 150000
                mileage_year: 15000
                vehicle: 2005 Toyota Corolla
                trim: CE
                depreciation_cost: [1682, 807, 706, 639, 572]
                total_cost: [10230, 8057, 7350, 7245, 9281]
                total_cost_sum: 42164

  # ---------------------------------------------------------------- Images
  /v3/images:
    servers:
      - url: https://images.vinaudit.com
    get:
      tags: [Images]
      operationId: getVehicleImages
      summary: Vehicle Images API
      description: >
        OEM-style rendered vehicle images by VIN or spec ID, with pose, color, background,
        size and format options. Pass either `vin` or `id`. JSON/XML responses return
        base64 image data.
      externalDocs:
        url: https://data.vinaudit.com/docs/api/images/vehicle-images
      parameters:
        - $ref: "#/components/parameters/vinOptional"
        - name: id
          in: query
          description: year_make_model_trim or year_make_model_trim_style ID.
          schema: { type: string, example: 2024_maserati_mc20_cielo }
        - name: format
          in: query
          schema: { type: string, enum: [json, xml, html], default: json }
        - name: pose
          in: query
          schema:
            type: string
            enum: [front_left, front_right, front, back_left, back_right, back, right, left]
            default: front_right
        - name: color
          in: query
          schema:
            type: string
            enum: [white, black, gray, grey, silver, blue, red, green, brown, beige, gold, orange, purple, yellow]
            default: white
        - name: background
          in: query
          schema: { type: string, enum: [white, gallery], default: white }
        - name: size
          in: query
          description: >
            small (640x480), medium (1280x960, default), large (2048x1536), xlarge (3000x2000),
            full (6000x4000), or custom WIDTHxHEIGHT (e.g. 1920x1080). json/xml only.
          schema: { type: string, default: medium, example: large }
        - name: granularity
          in: query
          schema: { type: string, enum: [trim, model], default: trim }
        - name: crop
          in: query
          description: Removes image padding.
          schema: { type: boolean, default: false }
      responses:
        "200":
          description: Rendered vehicle image(s)
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  success: { type: boolean }
                  error: { type: string }
                  images:
                    type: array
                    items:
                      type: object
                      properties:
                        content_type: { type: string, example: image/png }
                        data: { type: string, format: byte, description: Base64 image data }
                  ymmt:
                    type: object
                    properties:
                      year: { type: string }
                      make: { type: string }
                      model: { type: string }
                      trim: { type: string }
            text/html:
              schema: { type: string }

  /v2/remove-background:
    servers:
      - url: https://images.vinaudit.com
    get:
      tags: [Images]
      operationId: removeBackgroundByUrl
      summary: Vehicle Background Removal API (image URL)
      description: >
        AI background removal/replacement for exterior and interior vehicle photos.
        Use GET for simple image URL requests; use POST for uploads, base64 input and
        custom backgrounds.
      externalDocs:
        url: https://data.vinaudit.com/docs/api/images/background
      parameters:
        - name: image_url
          in: query
          required: true
          description: Public URL of the source image (.jpg, .png or .webp).
          schema: { type: string, format: uri, example: "https://images.vinaudit.com/samples/image1.jpg" }
        - name: background
          in: query
          schema: { $ref: "#/components/schemas/BackgroundMode" }
        - name: background_url
          in: query
          description: Public URL of a custom background image (custom_background).
          schema: { type: string, format: uri }
        - name: layout
          in: query
          schema: { type: string, enum: [center, crop, none], default: none }
        - name: effect
          in: query
          schema: { type: string, enum: [shadow, none], default: shadow }
        - name: background_prompt
          in: query
          description: Prompt for generative_background.
          schema: { type: string }
        - name: background_negative_prompt
          in: query
          schema: { type: string }
        - name: plate_replacement
          in: query
          schema: { type: string, enum: [image, none], default: none }
      responses:
        "200":
          $ref: "#/components/responses/BackgroundRemovalResult"
    post:
      tags: [Images]
      operationId: removeBackground
      summary: Vehicle Background Removal API (upload / base64 / custom background)
      externalDocs:
        url: https://data.vinaudit.com/docs/api/images/background
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              allOf:
                - $ref: "#/components/schemas/BackgroundRemovalRequest"
                - type: object
                  properties:
                    image_file: { type: string, format: binary }
                    background_file: { type: string, format: binary }
          application/json:
            schema: { $ref: "#/components/schemas/BackgroundRemovalRequest" }
      responses:
        "200":
          $ref: "#/components/responses/BackgroundRemovalResult"

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: key
      description: Your VinAudit API key.

  parameters:
    vinOptional:
      name: vin
      in: query
      description: Vehicle identification number.
      schema: { type: string, minLength: 17, maxLength: 17, example: 2T1BURHE3EC020936 }
    vinRequired:
      name: vin
      in: query
      required: true
      description: Vehicle identification number.
      schema: { type: string, minLength: 17, maxLength: 17, example: 1VXBR12EXCP901214 }
    country:
      name: country
      in: query
      description: usa (USD, miles) or canada (CAD, km).
      schema: { type: string, enum: [usa, canada], default: usa }
    user:
      name: user
      in: query
      required: true
      description: Account username (Vehicle History API).
      schema: { type: string }
    pass:
      name: pass
      in: query
      required: true
      description: Account password (Vehicle History API).
      schema: { type: string, format: password }
    historyFormat:
      name: format
      in: query
      required: true
      schema: { type: string, enum: [json, xml] }
    reportFormat:
      name: format
      in: query
      required: true
      schema: { type: string, enum: [json, xml, pdf] }
    skipspec:
      name: skipspec
      in: query
      description: Set to 1 if attributes are not needed.
      schema: { type: integer, enum: [0, 1] }
    mode:
      name: mode
      in: query
      description: Set to `test` for development (test VINs only).
      schema: { type: string, enum: [test] }
    callback:
      name: callback
      in: query
      description: JavaScript callback method name (format=json).
      schema: { type: string }
    reportType:
      name: type
      in: query
      description: USA or CAN report (format=pdf only).
      schema: { type: string, enum: [USA, CAN] }
    brand:
      name: brand
      in: query
      description: Set to 0 for an unbranded PDF (format=pdf only).
      schema: { type: integer, enum: [0, 1] }
    lang:
      name: lang
      in: query
      description: PDF language (format=pdf only).
      schema: { type: string, enum: [en, es] }

  responses:
    VehicleHistoryReport:
      description: Vehicle history report (JSON shown; XML and PDF also available)
      content:
        application/json:
          schema: { $ref: "#/components/schemas/VehicleHistoryReport" }
        application/pdf:
          schema: { type: string, format: binary }
    BackgroundRemovalResult:
      description: Processed image result
      content:
        application/json:
          schema:
            type: object
            properties:
              output_url: { type: string, format: uri, description: URL of the processed image }
              error:
                type: string
                description: invalid_input, unauthorized_request, no_data, request_failed, or blank.
              error_description: { type: string }

  schemas:
    MarketValue:
      type: object
      properties:
        success: { type: boolean }
        vin: { type: string, nullable: true }
        id: { type: string }
        vehicle: { type: string }
        mileage: { type: number }
        count: { type: integer, description: Data points used for the estimate }
        mean: { type: number }
        stdev: { type: number }
        certainty: { type: integer }
        period:
          type: array
          items: { type: string, format: date }
        prices:
          type: object
          properties:
            average: { type: number }
            below: { type: number }
            above: { type: number }
            distribution:
              type: array
              items:
                type: object
                properties:
                  group:
                    type: object
                    properties:
                      min: { type: number }
                      max: { type: number }
                      count: { type: integer }
        adjustments:
          type: object
          properties:
            mileage: { type: object, additionalProperties: true }
            history: { type: object, additionalProperties: true }
            condition: { type: object, additionalProperties: true }
            known_damage: { type: object, additionalProperties: true }
        type: { type: string, enum: [retail, wholesale, tradein] }

    SelectionNode:
      type: object
      properties:
        name: { type: string }
        id: { type: string }
        makes: { type: array, items: { $ref: "#/components/schemas/SelectionNode" } }
        models: { type: array, items: { $ref: "#/components/schemas/SelectionNode" } }
        trims: { type: array, items: { $ref: "#/components/schemas/SelectionNode" } }
        styles: { type: array, items: { $ref: "#/components/schemas/SelectionNode" } }

    VehicleHistoryReport:
      type: object
      properties:
        id: { type: string }
        vin: { type: string }
        date: { type: string, example: "2020-07-10 14:07:09 PDT" }
        attributes: { type: object, additionalProperties: true }
        titles:
          type: array
          items:
            type: object
            properties:
              date: { type: string, format: date }
              state: { type: string }
              vin: { type: string }
              meter: { type: string }
              meter_unit: { type: string, enum: [M, K] }
              current: { type: boolean }
        jsi:
          type: array
          description: Junk / salvage / insurance records.
          items: { type: object, additionalProperties: true }
        checks:
          type: array
          description: Title brand records.
          items: { type: object, additionalProperties: true }
        lien:
          type: array
          description: Lien, impound and export records (add-on).
          items: { type: object, additionalProperties: true }
        thefts:
          type: array
          description: Theft and theft recovery records (add-on).
          items: { type: object, additionalProperties: true }
        salvage:
          type: array
          description: Salvage auction records (add-on).
          items: { type: object, additionalProperties: true }
        accidents:
          type: array
          description: Accident records (add-on).
          items: { type: object, additionalProperties: true }
        sale:
          type: array
          description: Sale/listing records (add-on).
          items: { type: object, additionalProperties: true }
        clean:
          type: boolean
          description: True if free of title brands, salvage and insurance records.
        success: { type: boolean }

    FiveYearCost:
      type: array
      minItems: 5
      maxItems: 5
      items: { type: number }

    BackgroundMode:
      type: string
      enum: [white_background, transparent_background, custom_background, generative_background]

    BackgroundRemovalRequest:
      type: object
      description: Provide one source image -- image_url, image_base64 or image_file.
      properties:
        image_url: { type: string, format: uri }
        image_base64: { type: string, format: byte }
        background: { $ref: "#/components/schemas/BackgroundMode" }
        background_url: { type: string, format: uri }
        layout: { type: string, enum: [center, crop, none], default: none }
        effect: { type: string, enum: [shadow, none], default: shadow }
        background_prompt: { type: string }
        background_negative_prompt: { type: string }
        plate_replacement: { type: string, enum: [image, none], default: none }
        plate_base64:
          type: string
          format: byte
          description: Replacement plate image; required if plate_replacement=image.