generated: '2026-09-05'
method: derived
source: >-
  openapi/_original/carsxe-openapi.yml (harvested from https://api.carsxe.com/openapi.yaml),
  enriched from https://carsxe.com/docs/v1/* and https://carsxe.com/docs/v2/*
note: >-
  CarsXE's contract is deliberately thin on named schemas — components.schemas holds only Error,
  UsageLimitError, SuccessEnvelope and SpecsResponse, and most successful responses are typed as
  generic objects carried inside the envelope. So there is no rich $ref graph to walk. What follows
  is therefore the IDENTIFIER graph the API is actually organised around: three lookup keys (VIN,
  plate+region, year/make/model) that every product endpoint hangs off, plus the one entity CarsXE
  creates and gives an id to (a recalls batch). Relationships marked derived_from: parameters were
  read off the operation parameter sets, not invented.
envelope:
  name: SuccessEnvelope
  fields:
    success: boolean
    input: the echoed request parameters
    timestamp: ISO 8601
  note: errors replace `input`/`timestamp` with `message`, and add `usage` on a 429
identifiers:
  - id: vin
    name: Vehicle Identification Number
    format: 17 characters, ISO 3779
    validation: minLength 17, maxLength 17 in components.parameters.vin
    is_primary_key: true
    note: the dominant lookup key — 11 of 21 operations take it
  - id: plate
    name: Registration plate
    format: free-form string, qualified by country (ISO 3166-1 alpha-2) and, for US/CA/AU, state
    is_primary_key: false
    resolves_to: vin
  - id: ymm
    name: Year / Make / Model (+ optional trim)
    format: composite key
    is_primary_key: false
  - id: batchId
    name: Recalls batch identifier
    format: "brb_<random> (e.g. brb_mnablbn7_wvbaqv)"
    is_primary_key: true
    created_by: submitRecallsBatch
  - id: obd_code
    name: OBD-II diagnostic trouble code
    format: SAE J2012 (e.g. P0115, C1234)
    is_primary_key: true
entities:
  - entity: Vehicle
    key: vin
    description: the central subject; every product below is a projection of it
    produced_by: [getVehicleSpecs, getInternationalVinDecoder]
  - entity: Specifications
    key: vin
    produced_by: [getVehicleSpecs, getInternationalVinDecoder]
    fields: year, make, model, trim, engine, drivetrain, body style, dimensions, colours, equipment, options
  - entity: MarketValue
    key: vin
    produced_by: [getMarketValue, getMarketValueV2]
    fields: >-
      v1 — retail, tradeIn, loanValue, msrp, auctionValues; v2 — whole_*, retail_*, trade_in_*
      objects per condition tier (xclean, clean, avg, rough) with base, mileage and regional adjustments
    qualifiers: [state, mileage, condition]
  - entity: HistoryReport
    key: vin
    produced_by: [getVehicleHistory]
    fields: title records, junk/salvage events, insurance records, brands, odometer readings
  - entity: Recall
    key: vin or ymm
    produced_by: [getVehicleRecalls, getRecallsByYmm, getRecallsBatchResults]
    fields: campaign date, description, consequence, remedy, status
  - entity: LienTheftRecord
    key: vin
    produced_by: [getLienTheft]
    fields: lien holder, theft report, recovery date, status
  - entity: VehicleImage
    key: ymm (+ trim, colour, angle, photoType, size)
    produced_by: [getVehicleImages]
    fields: link, thumbnail, source, dimensions, licence
  - entity: PlateRecord
    key: plate + country (+ state, district)
    produced_by: [decodePlate, decodeUsPlate, decodePlateV2]
    fields: make, model, year, VIN where available — shape varies per country on v2
  - entity: PlateDetection
    key: image URL or base64
    produced_by: [recognizePlate]
    fields: detected plate text, confidence, bounding box, vehicle type
  - entity: VinDetection
    key: image URL or base64
    produced_by: [vinOcr]
    fields: detected VIN, confidence, bounding box, candidates
  - entity: YmmRecord
    key: ymm
    produced_by: [getYearMakeModel, getYearMakeModelOptions]
    fields: trims, features, options, packages; options endpoint returns one dropdown layer per call
  - entity: ObdCode
    key: obd_code
    produced_by: [decodeObdCode]
    fields: code, diagnosis, date
  - entity: RecallsBatch
    key: batchId
    created_by: submitRecallsBatch
    read_by: [getRecallsBatchStatus, getRecallsBatchResults, downloadRecallsBatchResults]
    fields: status, totalVins, processedVins, hitCount, hitRate, downloadUrl
    states: [processing, uploading, completed, partial, failed]
    limits: up to 10,000 VINs per batch; duplicates removed; CSV source under 5 MB
relationships:
  - {from: PlateRecord, to: Vehicle, type: belongs_to, via: vin, derived_from: documentation, note: "the plate decoder resolves a plate to a VIN, which then keys every other product"}
  - {from: PlateDetection, to: PlateRecord, type: has_one, via: plate, derived_from: documentation, note: "recognizePlate then decodePlateV2 is the documented two-step chain"}
  - {from: VinDetection, to: Vehicle, type: has_one, via: vin, derived_from: documentation}
  - {from: Specifications, to: Vehicle, type: belongs_to, via: vin, derived_from: parameters}
  - {from: MarketValue, to: Vehicle, type: belongs_to, via: vin, derived_from: parameters}
  - {from: HistoryReport, to: Vehicle, type: belongs_to, via: vin, derived_from: parameters}
  - {from: LienTheftRecord, to: Vehicle, type: belongs_to, via: vin, derived_from: parameters}
  - {from: Recall, to: Vehicle, type: belongs_to, via: vin, derived_from: parameters}
  - {from: Recall, to: YmmRecord, type: belongs_to, via: "year+make+model", derived_from: parameters, note: getRecallsByYmm needs no VIN}
  - {from: VehicleImage, to: YmmRecord, type: belongs_to, via: "year+make+model", derived_from: parameters}
  - {from: RecallsBatch, to: Recall, type: has_many, via: vin, derived_from: documentation}
  - {from: Vehicle, to: YmmRecord, type: has_one, via: "year+make+model", derived_from: documentation, note: "specs resolve a VIN into a YMM, closing the loop back to the VIN-less endpoints"}
chains:
  - name: plate photo to full profile
    steps: [recognizePlate, decodePlateV2, getVehicleSpecs, getVehicleRecalls, getMarketValueV2]
    note: the chain CarsXE demonstrates in its own MCP documentation
  - name: pre-purchase due diligence
    steps: [getVehicleSpecs, getVehicleHistory, getLienTheft, getVehicleRecalls, getMarketValueV2]
  - name: bulk recall sweep
    steps: [submitRecallsBatch, getRecallsBatchStatus, getRecallsBatchResults, downloadRecallsBatchResults]
    async: true
    webhook: bulk_recall_batch_complete