openapi: 3.1.0 info: title: CarsXE API description: | CarsXE is a B2B vehicle data API by PiWaves, LLC. It provides vehicle specifications (VIN decoding), market values, vehicle history, recalls, license plate decoding, vehicle images, plate/VIN image recognition, Year Make Model data and OBD code decoding. ## Authentication Most requests use a CarsXE API key in the `key` query parameter, e.g. `https://api.carsxe.com/specs?key=YOUR_API_KEY&vin=...`. Supported endpoints also accept x402 payment without a CarsXE key. Recalls Batch x402 follow-up requests use the scoped `X-CarsXE-Batch-Token` returned at submission. ## Caching Many endpoints cache upstream results. A cached response may include the message "The response is from the cache". version: "1.0.0" contact: name: CarsXE url: https://api.carsxe.com servers: - url: https://api.carsxe.com security: - ApiKeyQuery: [] tags: - name: Specifications description: VIN decoding and vehicle specifications - name: Market Value description: Vehicle market value by VIN - name: History description: Vehicle history reports - name: Recalls description: Safety recalls by VIN, including bulk batches - name: Plate Decoder description: Decode license plates into vehicle data - name: Images description: Vehicle images by make/model - name: Recognition description: Plate and VIN recognition from images - name: Year Make Model description: Year/make/model and OBD code endpoints - name: Lien & Theft description: Lien and theft records by VIN paths: /specs: get: operationId: getVehicleSpecs security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Specifications] summary: Vehicle Specifications (VIN decoder) description: | Decode a 17-character VIN and return detailed vehicle specifications, including attributes, colors, equipment and warranties. If the VIN cannot be decoded, an International VIN decoding check is run as a fallback unless `disableIntVINDecoding=1` is set. parameters: - $ref: "#/components/parameters/vin" - $ref: "#/components/parameters/format" - name: deepdata in: query required: false schema: type: string enum: ["1"] description: >- Request extra data. Set to `1` to use. Significantly slower than the regular request but retrieves additional data. - name: disableIntVINDecoding in: query required: false schema: type: string enum: ["1"] description: >- Set to `1` to disable the International VIN decoding fallback and return an error instead of a potential partial response. responses: "200": description: Vehicle specifications retrieved. content: application/json: schema: $ref: "#/components/schemas/SpecsResponse" example: success: true input: key: API_KEY vin: WBAFR7C57CC811956 attributes: year: "2012" make: BMW model: 5-Series trim: 535i style: SEDAN 4-DR type: Sedan/Saloon made_in: GERMANY doors: "4" fuel_type: Gasoline engine: 3.0L L6 DOHC 24V engine_cylinders: "6" transmission: 6-Speed Manual | 8-Speed Automatic drivetrain: RWD colors: - category: Interior name: Black Dakota Leather Interior - category: Exterior name: Alpine White equipment: abs_brakes: Std. air_conditioning: Std. warranties: - type: Basic miles: 50,000 mile months: 48 month timestamp: "2025-10-01T22:40:36.374Z" "400": description: Missing or invalid VIN. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Missing vin (vehicle identification number) "401": $ref: "#/components/responses/Unauthorized" "404": description: No data found for this VIN. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: >- No data found for this VIN. Try a deep search by setting deepdata=1 in your request "429": $ref: "#/components/responses/UsageLimitExceeded" "500": $ref: "#/components/responses/InternalServerError" /v1/international-vin-decoder: get: operationId: getInternationalVinDecoder security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Specifications] summary: International VIN Decoder description: Decode a non-US (international) VIN into vehicle attributes. parameters: - $ref: "#/components/parameters/vin" responses: "200": description: International VIN decoded. content: application/json: schema: type: object properties: success: type: boolean input: type: object additionalProperties: true attributes: type: object description: Decoded vehicle attributes. additionalProperties: true timestamp: type: string additionalProperties: true example: success: true input: vin: WF0MXXGBWM8R43240 attributes: vin: WF0MXXGBWM8R43240 vid: "1623" make: Ford model: Galaxy timestamp: "2025-04-11T00:05:36.457Z" "400": description: Missing VIN. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Missing vin (vehicle identification number) "401": $ref: "#/components/responses/Unauthorized" "404": description: No data found for this VIN. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: No data found for this VIN "429": $ref: "#/components/responses/UsageLimitExceeded" "500": $ref: "#/components/responses/InternalServerError" /v1/recalls: get: operationId: getVehicleRecalls security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Recalls] summary: Vehicle Recalls description: Retrieve open safety recalls for a vehicle by VIN. parameters: - $ref: "#/components/parameters/vin" responses: "200": description: Recall data retrieved. content: application/json: schema: type: object properties: success: type: boolean input: type: object additionalProperties: true data: type: object description: Recall report for the VIN. additionalProperties: true timestamp: type: string additionalProperties: true example: success: true input: key: API_KEY vin: 1C4JJXR64PW696340 data: uuid: d1269d6b-54a2-4bf3-8119-1c8fdb4f0563 vin: 1C4JJXR64PW696340 manufacturer: FCA US LLC model_year: "2023" timestamp: "2025-10-03T08:46:03.701Z" "400": description: Missing VIN. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Missing vin (vehicle identification number) "401": $ref: "#/components/responses/Unauthorized" "404": description: No recall data found for this VIN. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: No data found for this VIN "429": $ref: "#/components/responses/UsageLimitExceeded" "500": $ref: "#/components/responses/InternalServerError" /v1/recalls-ymm: get: operationId: getRecallsByYmm security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Recalls] summary: Recalls by Year, Make & Model description: Retrieve open safety recalls for a vehicle by year, make, and model — no VIN required. parameters: - name: year in: query required: true schema: type: string description: The 4-digit model year (e.g. `2019`). - name: make in: query required: true schema: type: string description: The vehicle manufacturer name (e.g. `Toyota`). Case-insensitive. - name: model in: query required: true schema: type: string description: The vehicle model name (e.g. `Camry`). Case-insensitive. responses: "200": description: Recall data retrieved. content: application/json: schema: type: object properties: success: type: boolean input: type: object properties: year: type: string make: type: string model: type: string data: type: object properties: make: type: string model: type: string model_year: type: string recall_count: type: integer has_recalls: type: boolean recalls: type: array items: type: object additionalProperties: true timestamp: type: string example: success: true input: year: "2026" make: TOYOTA model: COROLLA data: make: TOYOTA model: COROLLA model_year: "2026" recall_count: 1 has_recalls: true recalls: - nhtsa_campaign_number: 26V110000 manufacturer: Toyota Motor Engineering & Manufacturing park_it: false park_outside: false over_the_air_update: false report_received_date: 25/02/2026 component: EXTERIOR LIGHTING:HEADLIGHTS summary: Toyota is recalling certain 2026 Corolla vehicles. consequence: Incorrectly aimed headlights can reduce driver visibility. remedy: Dealers will replace both front headlight assemblies, free of charge. notes: null timestamp: "2026-06-29T12:00:45.786Z" "400": description: Missing or invalid year, make, or model. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Missing required parameters "401": $ref: "#/components/responses/Unauthorized" "404": description: Feature not available on this plan. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: This feature is not enabled for your account "429": $ref: "#/components/responses/UsageLimitExceeded" "500": $ref: "#/components/responses/InternalServerError" /v1/recalls-batch/submit: post: operationId: submitRecallsBatch security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Recalls] summary: Submit a bulk recalls batch description: | Submit up to 10,000 VINs for asynchronous recall processing. Provide VINs as a JSON array (`vins`), inline CSV text (`csv`), or an HTTPS link to a CSV file (`csvUrl`). Optionally provide a `webhookUrl` that CarsXE will POST to when the batch finishes. Poll the status endpoint or wait for the webhook, then fetch results. x402 submissions must use the JSON `vins` array. The `csv` and `csvUrl` forms require CarsXE API-key authentication. requestBody: required: true content: application/json: schema: type: object properties: vins: type: array items: type: string description: Array of 17-character VINs (max 10,000 per batch). csv: type: string description: >- Inline CSV text containing VINs. Available with CarsXE API-key authentication only; x402 does not accept this form. csvUrl: type: string description: >- HTTPS link to a CSV file of VINs (max 5 MB) hosted on a supported storage provider (e.g. S3, GCS, Firebase, Dropbox). Available with CarsXE API-key authentication only; x402 does not accept this form. webhookUrl: type: string description: >- HTTPS URL for a customer webhook. CarsXE POSTs a JSON payload when the batch finishes. Must be a valid HTTPS URL allowed by CarsXE validation rules. example: vins: - 1HGBH41JXMN109186 - 5YJSA1E26HF000001 webhookUrl: https://example.com/webhooks/carsxe-recalls responses: "202": description: Batch accepted and queued for processing. content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: batchId: type: string status: type: string totalVins: type: integer processedVins: type: integer batchToken: type: string description: >- Opaque batch-scoped credential returned only for x402 submissions. Send it in X-CarsXE-Batch-Token on follow-up requests. additionalProperties: true message: type: string additionalProperties: true example: success: true data: batchId: brb_mnablbn7_wvbaqv status: uploading totalVins: 3 processedVins: 0 message: >- Batch submitted and queued for processing. Poll the status endpoint or wait for the webhook. "400": description: >- Invalid request body — missing VINs, invalid VINs, more than 10,000 VINs, invalid `webhookUrl`, or a `csvUrl` that is invalid / not allowed / too large. content: application/json: schema: $ref: "#/components/schemas/Error" examples: missingVins: value: success: false message: >- Request body must include at least one of: "vins" (non-empty array), "csv" (text), or "csvUrl" (https link to a CSV) with valid 17-character VINs. invalidVin: value: success: false message: >- One or more VINs are invalid. Each VIN must be exactly 17 characters. tooManyVins: value: success: false message: >- Maximum 10,000 VINs per batch. Split your request into multiple batches. "401": $ref: "#/components/responses/Unauthorized" "405": description: Method not allowed (only POST is accepted). content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Only POST allowed. Send JSON body with "vehicles" array. "429": $ref: "#/components/responses/UsageLimitExceeded" "500": $ref: "#/components/responses/InternalServerError" "502": description: Could not download the CSV from `csvUrl`. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: >- Could not download the CSV from csvUrl. Check the link and try again. /v1/recalls-batch/status: get: security: - ApiKeyQuery: [] - RecallsBatchToken: [] operationId: getRecallsBatchStatus tags: [Recalls] summary: Get bulk recalls batch status description: Check the processing status of a previously submitted batch. parameters: - $ref: "#/components/parameters/batchId" - $ref: "#/components/parameters/recallsBatchToken" responses: "200": description: Batch status retrieved. content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: batchId: type: string numericBatchId: type: integer status: type: string totalVins: type: integer additionalProperties: true additionalProperties: true example: success: true data: batchId: brb_mnablbn7_wvbaqv numericBatchId: 200426 status: completed totalVins: 3 "400": description: Missing batchId parameter. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Missing batchId parameter "401": $ref: "#/components/responses/Unauthorized" "404": description: Batch not found or not accessible with this API key. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: >- Batch not found or you do not have access to this batch. /v1/recalls-batch/results: get: security: - ApiKeyQuery: [] - RecallsBatchToken: [] operationId: getRecallsBatchResults tags: [Recalls] summary: Get bulk recalls batch results description: >- Fetch the per-VIN recall results of a completed batch as JSON. parameters: - $ref: "#/components/parameters/batchId" - $ref: "#/components/parameters/recallsBatchToken" responses: "200": description: Batch results retrieved. content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: job: type: object additionalProperties: true results: type: array items: type: object properties: vin: type: string hasRecalls: type: boolean recallCount: type: integer recalls: type: array items: type: object additionalProperties: true additionalProperties: true additionalProperties: true example: success: true data: job: batchId: brb_mnablbn7_wvbaqv numericBatchId: 200426 status: completed results: - vin: 1HGBH41JXMN109186 hasRecalls: true recallCount: 1 - vin: 5YJSA1E26HF000001 hasRecalls: false recallCount: 0 "400": description: Missing batchId parameter. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Missing batchId parameter "401": $ref: "#/components/responses/Unauthorized" "404": description: Batch not found or not accessible with this API key. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: >- Batch not found or you do not have access to this batch. "409": description: Batch processing is not yet complete. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: >- Batch processing is not yet complete. Check status and try again later. /v1/recalls-batch/download: get: security: - ApiKeyQuery: [] - RecallsBatchToken: [] operationId: downloadRecallsBatchResults tags: [Recalls] summary: Download bulk recalls batch results description: Download the results of a completed batch as CSV. parameters: - $ref: "#/components/parameters/batchId" - $ref: "#/components/parameters/recallsBatchToken" responses: "200": description: CSV results file. content: text/csv: schema: type: string "400": description: Missing batchId parameter. "401": $ref: "#/components/responses/Unauthorized" "404": description: Batch not found or not accessible with these credentials. "409": description: Batch processing is not yet complete. /platedecoder: get: operationId: decodePlate security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Plate Decoder] summary: License Plate Decoder (v1) description: | Decode a license plate into vehicle data. Internally proxies to the v2 plate decoder. The `state` parameter accepts a two-letter US state code, Australian state, or one of the legacy country codes `BR`, `UK`, `IR`, `IT`, `ES`, `IND`, `MX`, `NZ`. parameters: - name: plate in: query required: true schema: type: string description: The vehicle registration number or license plate number. - name: state in: query required: true schema: type: string description: >- The two letter state code (US) such as `CA` or `NY`, Australian state, or Brazil `BR`, United Kingdom `UK`, Ireland `IR`, Italy `IT`, Spain `ES`, India `IND`, Mexico `MX`, New Zealand `NZ`. - name: country in: query required: false schema: type: string description: Country code, e.g. Australia `AU`. Optional for `US`. - $ref: "#/components/parameters/format" responses: "200": description: Plate decoded. content: application/json: schema: type: object properties: success: type: boolean input: type: object additionalProperties: true vin: type: string additionalProperties: true example: success: true input: plate: 7XER187 state: CA country: US vin: 3KPFK4A78HE103497 assembly: Mexico Description: Kia Forte LX BodyStyle: Sedan RegistrationYear: "2017" EngineSize: 2.0L I4 MPI CarMake: Kia CarModel: Forte "400": description: Missing plate or state. content: application/json: schema: $ref: "#/components/schemas/Error" examples: missingPlate: value: success: false message: >- Missing vehicle registration number or license plate number missingState: value: success: false message: Missing 2 letter state code "401": $ref: "#/components/responses/Unauthorized" "404": description: >- No data found for this plate (passed through from the v2 decoder). content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Could not fetch data "429": $ref: "#/components/responses/UsageLimitExceeded" "502": description: Upstream plate decoder request failed. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Could not fetch data "504": description: Upstream plate decoder request timed out. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Request timed out. Please try again. /v1/us-platedecoder: get: operationId: decodeUsPlate security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Plate Decoder] summary: US Vehicle Plate Decoder description: | Look up a US vehicle by license plate number and state. Returns the VIN, year, make, model, trim, engine, body style, transmission, drive type, fuel type and exterior color. Optionally decodes the VIN to include the full vehicle specifications object. Accepts plates from all 50 US states, the District of Columbia (DC) and Puerto Rico (PR). This endpoint is **not** available on the free Sandbox tier. parameters: - name: plate in: query required: true schema: type: string description: The vehicle registration number or license plate number. - name: state in: query required: true schema: type: string description: >- Two-letter abbreviation for one of the 50 US states, the District of Columbia (`DC`), or Puerto Rico (`PR`). - name: decodeVIN in: query required: false schema: type: string enum: ["true", "1"] description: >- Set to `true` or `1` to decode the resolved VIN and include a `vehicle_specs` object in the response (identical in shape to the Specifications endpoint response). responses: "200": description: Plate decoded successfully. content: application/json: schema: type: object properties: success: type: boolean input: type: object properties: plate: type: string state: type: string additionalProperties: true vin: type: string year: type: string make: type: string model: type: string trim: type: string description: type: string engine_size: type: string body_style: type: string transmission: type: string drive_type: type: string fuel_type: type: string color: type: string vehicle_specs: $ref: "#/components/schemas/SpecsResponse" description: >- Full vehicle specifications (only present when `decodeVIN=true`). additionalProperties: true example: success: true input: plate: H37SFS state: NJ vin: 1GNSCGKC0JR318026 year: "2018" make: Chevrolet model: Suburban trim: LS description: 2018 Chevrolet Suburban engine_size: 5.3L V8 OHV 16V body_style: SUV transmission: Automatic drive_type: RWD fuel_type: Flexible-Fuel color: Black "400": description: Missing plate, state, or API key. content: application/json: schema: $ref: "#/components/schemas/Error" examples: missingPlate: value: success: false message: >- Missing vehicle registration number or license plate number missingState: value: success: false message: Missing 2 letter state code "401": $ref: "#/components/responses/Unauthorized" "404": description: No data found for this plate/state combination. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Could not fetch data "429": $ref: "#/components/responses/UsageLimitExceeded" "500": $ref: "#/components/responses/InternalServerError" /v1/lien-theft: get: operationId: getLienTheft security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Lien & Theft] summary: Lien & Theft records description: >- Check a VIN for active lien and theft records (US). parameters: - $ref: "#/components/parameters/vin" responses: "200": description: Lien/theft data retrieved. content: application/json: schema: type: object properties: success: type: boolean input: type: object additionalProperties: true timestamp: type: string year: type: integer make: type: string model: type: string type: type: string events: type: array items: type: object additionalProperties: true trim_data: type: object additionalProperties: true additionalProperties: true example: success: true input: vin: 2C3CDXFG1FH762860 timestamp: "2025-12-07T20:32:11.027Z" year: 2015 make: DODGE model: Charger type: CAR events: - event: Recovered Theft location: OH details_list: - The vehicle is reported to be an Recovered Theft. "400": description: Missing or invalid VIN. content: application/json: schema: $ref: "#/components/schemas/Error" examples: missingVin: value: success: false message: Missing vin (vehicle identification number) wrongLength: value: success: false message: Wrong VIN length, must be 17 characters "401": $ref: "#/components/responses/Unauthorized" "404": description: No lien or theft data found for this VIN. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: No lien or theft data found for this VIN "429": $ref: "#/components/responses/UsageLimitExceeded" /images: get: operationId: getVehicleImages security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Images] summary: Vehicle Images description: Retrieve images of a vehicle by make, model and other filters. parameters: - name: make in: query required: true schema: type: string description: The vehicle make. - name: model in: query required: true schema: type: string description: The vehicle model. - name: year in: query required: false schema: type: string description: The vehicle year. - name: trim in: query required: false schema: type: string description: The vehicle trim. - name: color in: query required: false schema: type: string description: The vehicle color. - name: transparent in: query required: false schema: type: boolean description: >- Prioritize images with transparent background. Defaults to `true`. - name: angle in: query required: false schema: type: string enum: [front, side, back] description: The angle to show the car in. - name: photoType in: query required: false schema: type: string enum: [interior, exterior, engine] description: >- Request images of the interior, exterior or engine. Can only be used in conjunction with year, make, model and trim query params. - name: size in: query required: false schema: type: string enum: [Small, Medium, Large, Wallpaper, All] description: Request images of a given size. Defaults to all sizes. - name: license in: query required: false schema: type: string example: ModifyCommercially description: >- Filter images by usage-rights labels supplied by the hosting site. This does not grant a license; confirm each image's contextLink before reuse. Presets: Public (public domain only); Share (free to use or share, including NonCommercial and NoDerivatives); ShareCommercially (free to share commercially; excludes NonCommercial, includes NoDerivatives); Modify (free to modify; excludes NoDerivatives, includes NonCommercial); ModifyCommercially (free to modify commercially; public domain, attribution, and ShareAlike only). Or pass specific tokens as a comma-separated list: cc_publicdomain (public domain), cc_attribute (attribution; commercial use and modification, with credit when shared), cc_sharealike (ShareAlike; shared adaptations use the same license), cc_noncommercial (NonCommercial), cc_nonderived (NoDerivatives). Prefix a token with - to exclude it. At least one included token is required. Leave blank to return all images. - $ref: "#/components/parameters/format" responses: "200": description: Images retrieved. content: application/json: schema: type: object properties: success: type: boolean error: type: string images: type: array items: type: object properties: mime: type: string link: type: string contextLink: type: string height: type: integer width: type: integer byteSize: type: integer thumbnailLink: type: string accentColor: type: string additionalProperties: true query: type: object additionalProperties: true additionalProperties: true example: success: true images: - mime: image/png link: https://bit.ly/34tpueu contextLink: https://www.mariettatoyota.com/toyota-tacoma/ height: 272 width: 1000 byteSize: 56662 thumbnailLink: https://bit.ly/34xewVr accentColor: B51617 query: year: "2018" make: toyota model: tacoma color: blue format: json "401": $ref: "#/components/responses/Unauthorized" "404": description: No images found for this query. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: No images found "429": $ref: "#/components/responses/UsageLimitExceeded" "500": description: Missing make/model, or the image search failed. content: application/json: schema: $ref: "#/components/schemas/Error" examples: missingMakeModel: value: success: false message: >- Please supply a make and model. Visit https://carsxe.com/docs for more information cannotAccessInternet: value: success: false message: Cannot access the internet at this time /marketvalue: get: operationId: getMarketValue security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Market Value] summary: Vehicle Market Value (v1) description: >- Get the market value of a vehicle by VIN, including retail, trade-in and auction values. parameters: - $ref: "#/components/parameters/vin" - $ref: "#/components/parameters/format" responses: "200": description: Market value retrieved. content: application/json: schema: type: object properties: success: type: boolean vin: type: string retail: type: string description: Retail price of the vehicle. tradeIn: type: string description: The trade in price of the vehicle. roughTradeIn: type: string averageTradeIn: type: string loanValue: type: string msrp: type: string tradeInValues: type: array items: type: object properties: date: type: string value: type: string additionalProperties: true auctionValues: type: object additionalProperties: true additionalProperties: true example: retail: "16075" tradeIn: "13575" roughTradeIn: "10250" averageTradeIn: "12050" loanValue: "12225" uid: 1172227 msrp: "52250" tradeInValues: - date: "2018-08-01T00:00:00.000Z" value: "13575" - date: "2018-07-01T00:00:00.000Z" value: "13600" auctionValues: lowAuctionValue: 9050 averageAuctionValue: 11925 highAuctionValue: 14825 dateRange: 8/6/2018 - 8/12/2018 "400": description: Missing VIN. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Missing vin (vehicle identification number) "401": $ref: "#/components/responses/Unauthorized" "404": description: No data found for this VIN. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: No data found for this VIN "429": $ref: "#/components/responses/UsageLimitExceeded" "500": $ref: "#/components/responses/InternalServerError" /history: get: operationId: getVehicleHistory security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [History] summary: Vehicle History description: >- Retrieve a vehicle history report by VIN, including title, brand, junk/salvage and insurance records. parameters: - $ref: "#/components/parameters/vin" - $ref: "#/components/parameters/format" responses: "200": description: History report retrieved. content: application/json: schema: type: object properties: success: type: boolean vin: type: string junkAndSalvageInformation: type: array items: type: object additionalProperties: true insuranceInformation: type: array items: type: object additionalProperties: true brandsRecordCount: type: number brandsInformation: type: array items: type: object additionalProperties: true vinChanged: type: boolean currentTitleInformation: type: array items: type: object additionalProperties: true historyInformation: type: array items: type: object additionalProperties: true additionalProperties: true "400": description: Missing or invalid VIN. content: application/json: schema: $ref: "#/components/schemas/Error" examples: missingVin: value: success: false message: Missing vin (vehicle identification number) wrongLength: value: success: false message: Wrong VIN length, must be 17 characters "401": $ref: "#/components/responses/Unauthorized" "403": description: This API key has been blocked for the History API. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: >- This API key has been blocked, please contact support if you believe this is an error. "404": description: No history data found for this VIN. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: No data found for this VIN "429": $ref: "#/components/responses/UsageLimitExceeded" "500": $ref: "#/components/responses/InternalServerError" /platerecognition: post: operationId: recognizePlate security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Recognition] summary: Plate Image Recognition description: >- Extract a license plate number from an image of a vehicle. Send a JSON body containing an `image_url` field with a URL to the image. requestBody: required: true content: application/json: schema: type: object required: [image_url] properties: image_url: type: string description: URL to an image of a vehicle's license plate. example: image_url: https://example.com/car-photo.jpg responses: "200": description: Plate recognized. content: application/json: schema: type: object properties: success: type: boolean message: type: string results: type: array items: type: object properties: plate: type: string box: type: object additionalProperties: true region: type: object additionalProperties: true additionalProperties: true processing_time: type: number additionalProperties: true example: success: true message: "" results: - box: xmin: 2045 ymin: 1400 xmax: 2732 plate: 9djc652 region: code: us-ca score: 0.849 processing_time: 117.822 "400": description: Missing image URL in the request body. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Missing upload URL "401": $ref: "#/components/responses/Unauthorized" "404": description: No plate could be recognized in the image. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: No plates detected in image "429": $ref: "#/components/responses/UsageLimitExceeded" "500": description: Plate recognition service error. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Could not get information at this time /v1/vinocr: post: operationId: vinOcr security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Recognition] summary: VIN OCR description: >- Extract a VIN from a photo. Send a JSON body containing an `image_url` field with either a URL to an image or a base64-encoded image string. requestBody: required: true content: application/json: schema: type: object required: [image_url] properties: image_url: type: string description: >- URL to an image, or the base64 string of the image. example: image_url: https://example.com/vin-plate.jpg responses: "200": description: VIN extracted from the image. content: application/json: schema: type: object properties: success: type: boolean vin: type: string box: type: object additionalProperties: true confidence: type: number candidates: type: array items: type: object additionalProperties: true additionalProperties: true example: success: true vin: JHLRD77874C026456 box: xmin: 257 xmax: 1673 ymin: 635 ymax: 793 confidence: 0.9834251403808594 candidates: - vin: JHLRD77874C026456 confidence: 0.9834251403808594 "400": description: >- Missing API key, missing image, invalid image data, image processing failure, or no text detected. content: application/json: schema: $ref: "#/components/schemas/Error" examples: missingKey: value: success: false message: Missing API key missingImage: value: success: false message: Missing image data invalidImage: value: success: false message: >- Invalid image data format. Must be a valid URL or base64 encoded string. noText: value: success: false message: No text detected in the image "401": description: User with this API key is not active. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: >- User with this API key is not active. To activate update your billing on https://carsxe.com/dashboard/billing "404": description: API key not found, or no valid VIN found in the image. content: application/json: schema: $ref: "#/components/schemas/Error" examples: userNotFound: value: success: false message: >- User with this API key was not found or the API key is disabled noVin: value: success: false message: No valid VIN candidates found in the image "429": $ref: "#/components/responses/UsageLimitExceeded" /v1/ymm: get: operationId: getYearMakeModel security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Year Make Model] summary: Year Make Model description: >- Look up vehicle data by year, make and model (and optionally trim) without a VIN. parameters: - name: year in: query required: true schema: type: string description: >- The manufacturing year of the vehicle (numeric, between 1900 and the current model year plus one). - name: make in: query required: true schema: type: string description: The manufacturer of the vehicle (e.g., Toyota, Ford, BMW). - name: model in: query required: true schema: type: string description: The specific model of the vehicle (e.g., Camry, F-150, X5). - name: trim in: query required: false schema: type: string description: The vehicle trim (e.g., XLE, XSE). - name: allTrimOptions in: query required: false schema: type: string enum: ["1"] description: >- Return all trim options available for the year, make and model. Set to `1` to use. responses: "200": description: Vehicle matched. content: application/json: schema: type: object properties: success: type: boolean bestMatch: type: object additionalProperties: true trimOptions: type: array items: type: object additionalProperties: true input: type: object additionalProperties: true timestamp: type: string additionalProperties: true example: bestMatch: make: Toyota model: Camry year: "2023" name: XLE 4dr Sedan (3.5L 6cyl 8A) trimOptions: [] success: true input: year: "2023" make: Toyota model: Camry trim: XLE timestamp: "2024-03-19T12:00:00.000Z" "400": description: Missing or invalid year, make or model. content: application/json: schema: $ref: "#/components/schemas/Error" examples: missing: value: success: false message: Missing year, make, or model invalidYear: value: success: false message: >- Invalid year. Provide a numeric year between 1900 and the current model year plus one. "401": $ref: "#/components/responses/Unauthorized" "404": description: No vehicle matched the specified year, make and model. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: >- No vehicle found matching the specified year, make, and model. Try case-sensitive search such as "2023 Toyota Camry" "429": $ref: "#/components/responses/UsageLimitExceeded" "500": description: Could not fetch data. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Could not fetch data /v1/ymm-options: get: operationId: getYearMakeModelOptions security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Year Make Model] summary: Year Make Model Options description: >- Populate Year, Make, Model, and Variant dropdown menus. Each response returns exactly one layer. `dimension` is optional — when omitted, the response shape is inferred from `make`/`model`/`year`. Billing: most calls cost 1 unit. `dimension=variants` with `year` + `make` (no `model`) costs 1 unit per model; the response includes `modelCount`. Required filters help you get better, more relevant results. `year`, `make`, and `model` can be combined for reversed lookups (e.g. years for a given make+model). parameters: - name: dimension in: query required: false schema: type: string enum: ["years", "makes", "models", "trims", "variants"] description: >- Return exactly this array when required filters are present. If omitted, the response is inferred automatically from `make`/`model`/`year`. - name: year in: query required: false schema: type: string description: >- Filter to a specific manufacturing year. Required when filtering by `model` without `make`. - name: make in: query required: false schema: type: string description: >- Filter to a specific manufacturer (e.g., Toyota, Ford, Lexus). Required for `dimension=models`. - name: model in: query required: false schema: type: string description: >- Filter to a specific model (e.g., Camry, F-150, LX). Required for `dimension=trims` and for `dimension=variants` unless both `year` and `make` are set. - name: trim in: query required: false schema: type: string description: >- Optional substring filter on trim names. Only applied when querying `dimension=trims` or `dimension=variants`. responses: "200": description: Distinct values for the requested (or inferred) dimension(s). content: application/json: schema: type: object properties: success: type: boolean input: type: object additionalProperties: true message: type: string description: >- Optional guidance when the returned layer differs from the requested dimension or when explaining how to get better results. years: type: array items: type: integer makes: type: array items: type: string models: type: array items: type: string trims: type: array items: type: string variants: type: array items: type: string modelCount: type: integer description: >- Present only for bulk variants (`dimension=variants` + year + make, no model). Number of distinct models, which is also the amount billed — except a zero-match query, which returns 0 but still bills a minimum of 1 unit. additionalProperties: true examples: variants: summary: make+model given -> variants only value: success: true input: year: 2026 make: Toyota model: Tacoma variants: - Tacoma Limited - Tacoma SR - Tacoma SR5 - Tacoma TRD Off-Road - Tacoma TRD PreRunner - Tacoma TRD Pro - Tacoma TRD Sport - Tacoma Trailhunter modelsForMakeOnly: summary: make given, no model -> models only (one layer per response) value: success: true input: year: 2026 make: Toyota models: ["4Runner", "Camry", "Corolla", "Tacoma", "Tundra"] variantsForYearAndModel: summary: year+model given, no make -> variants only value: success: true input: year: 2026 model: Tacoma variants: ["Tacoma Limited", "Tacoma SR", "Tacoma SR5", "Tacoma TRD Pro"] variantsForYearAndMake: summary: dimension=variants with year+make -> billed per model (modelCount) value: success: true input: dimension: variants year: 2025 make: Lexus variants: - ES 250 - ES 300h - GX 550 Premium - IS 300 - LX 600 Premium - RX 350 modelCount: 6 variantsFallbackToModels: summary: dimension=variants with make only (no year) -> models + message value: success: true input: dimension: variants make: Toyota message: >- To receive variants, include a model filter with this make. Models are returned instead. models: ["4Runner", "Camry", "Corolla", "Tacoma", "Tundra"] yearsForMakeModel: summary: "Reversed combination: dimension=years filtered by make+model" value: success: true input: dimension: years make: Lexus model: TX years: [2026, 2025, 2024] "400": description: >- Invalid dimension, invalid year, missing required filters, or model without make/year. content: application/json: schema: $ref: "#/components/schemas/Error" examples: invalidDimension: value: success: false message: >- Invalid dimension. Must be one of: years, makes, models, trims, variants. invalidYear: value: success: false message: >- Invalid year. Provide a numeric year between 1900 and the current model year plus one. missingMakeForModels: value: success: false message: >- A make filter is required to list models. Add make=... to get better results. missingMakeOrModelForTrimsVariants: value: success: false message: >- Trims and variants require a make or model filter. Add make=... or model=... to get better results. missingYearWhenModelWithoutMake: value: success: false message: >- When filtering by model without make, a year filter is required. Add year=... to get better results. missingMakeWhenModelAmbiguous: value: success: false message: >- This model name appears under multiple makes. Add make=... together with year and model to get better results. "401": $ref: "#/components/responses/Unauthorized" "429": $ref: "#/components/responses/UsageLimitExceeded" "500": description: Could not fetch data. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Could not fetch data /obdcodesdecoder: get: operationId: decodeObdCode security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Year Make Model] summary: OBD Codes Decoder description: Decode an OBD-II diagnostic trouble code (e.g. P0115). parameters: - name: code in: query required: true schema: type: string description: The OBD code. responses: "200": description: OBD code decoded. content: application/json: schema: type: object properties: success: type: boolean diagnosis: type: string date: type: string code: type: string additionalProperties: true example: success: true diagnosis: Engine Coolant Temperature Circuit Malfunction date: "2020-07-04T21:44:39.767Z" code: P0115 "400": description: Missing OBD code. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Missing OBD code "401": $ref: "#/components/responses/Unauthorized" "404": description: The OBD code could not be found. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Could not find code P9999 "429": $ref: "#/components/responses/UsageLimitExceeded" /v2/platedecoder: get: operationId: decodePlateV2 security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Plate Decoder] summary: License Plate Decoder (v2) description: | Decode a license plate into vehicle data across 60+ supported countries. `country` is an ISO 3166-1 alpha-2 code (optional for `US`). `state` is required for `US`, `AU` and `CA`. For Pakistan (`PK`) a `district` is also required for the Khyber-Pakhtunkhwa province. For Spain (`ES`), set `require_vin=true` to always include a VIN. Additional charges apply: when `require_vin=true`, the request is billed 2x and usage counts 2x. parameters: - name: plate in: query required: true schema: type: string description: The vehicle registration number or license plate number. - name: country in: query required: false schema: type: string description: >- ISO 3166-1 alpha-2 country code such as `AU` for Australia or `ZA` for South Africa. Optional for `US`. - name: state in: query required: false schema: type: string description: >- The two letter state code (US) such as `CA` or `NY`, an Australian state (e.g. `NSW`, `VIC`), or a Canadian province (e.g. `ON`). Required only for `US`, `AU` and `CA`. - name: district in: query required: false schema: type: string description: >- The district of the vehicle registration number. Required for Pakistan (`PK`) plates registered in the Khyber-Pakhtunkhwa province. - name: require_vin in: query required: false schema: type: boolean description: >- Only supported when `country=ES`. Set to `true` to always include a VIN. The request is billed 2x and usage counts 2x. responses: "200": description: Plate decoded. content: application/json: schema: type: object properties: success: type: boolean input: type: object additionalProperties: true description: type: string make: type: string model: type: string trim: type: string vin: type: string year: type: string additionalProperties: true example: success: true input: plate: 7XER187 state: CA country: US description: Kia Forte LX make: Kia model: Forte trim: LX vin: 3KPFK4A78HE103497 style: Sedan 4D year: "2017" assembly: Mexico fuel_type: Gasoline color: White body_style: Sedan engine_size: 2.0L I4 MPI drive_type: FWD transmission: Automatic "400": description: >- Missing plate, or `require_vin` used with a country other than ES. content: application/json: schema: $ref: "#/components/schemas/Error" examples: missingPlate: value: success: false message: >- Missing vehicle registration number or license plate number requireVin: value: success: false message: >- The require_vin parameter is only supported when country=ES. "401": $ref: "#/components/responses/Unauthorized" "404": description: >- Invalid state/country/district, or no data found for this plate. content: application/json: schema: $ref: "#/components/schemas/Error" examples: invalidState: value: success: false message: Invalid state or country code. invalidDistrict: value: success: false message: Invalid district notFound: value: success: false message: >- Plate searches for this country have been disabled, or No data found for this plate "429": $ref: "#/components/responses/UsageLimitExceeded" /v2/marketvalue: get: operationId: getMarketValueV2 security: - ApiKeyQuery: [] - X402Payment: [] - {} tags: [Market Value] summary: Vehicle Market Value (v2) description: >- Get detailed market values for a VIN, including wholesale, retail and trade-in values across condition tiers, with optional adjustments for US state, mileage and condition. parameters: - $ref: "#/components/parameters/vin" - name: state in: query required: false schema: type: string description: The US state of the vehicle to get the market value for. - name: mileage in: query required: false schema: type: number description: >- The current mileage of the vehicle used to adjust the market value. Must be a valid numeric value. - name: condition in: query required: false schema: type: string enum: [excellent, clean, average, rough] description: The overall condition of the vehicle. responses: "200": description: Market value retrieved. content: application/json: schema: type: object properties: uid: type: string input: type: object additionalProperties: true publish_date: type: string state: type: string country: type: string model_year: type: string make: type: string model: type: string series: type: string style: type: string class_name: type: string whole_xclean: type: object additionalProperties: true whole_clean: type: object additionalProperties: true whole_avg: type: object additionalProperties: true whole_rough: type: object additionalProperties: true retail_xclean: type: object additionalProperties: true retail_clean: type: object additionalProperties: true retail_avg: type: object additionalProperties: true retail_rough: type: object additionalProperties: true additionalProperties: true example: uid: FDE60872 input: vin: WBAFR7C57CC811956 country: US publish_date: 4/8/2025 state: NT country: US model_year: "2012" make: BMW model: 5-Series series: 535i style: 4D Sedan class_name: Luxury Car whole_clean: base_whole_clean: 5300 mileage_whole_clean: 0 add_deduct_whole_clean: 0 regional_whole_clean: 0 retail_clean: base_retail_clean: 9325 mileage_retail_clean: 0 add_deduct_retail_clean: 0 regional_retail_clean: 0 "400": description: Missing/invalid VIN, mileage or condition. content: application/json: schema: $ref: "#/components/schemas/Error" examples: missingVin: value: success: false message: Missing vin (vehicle identification number) wrongLength: value: success: false message: Wrong VIN length, must be 17 characters invalidCondition: value: success: false message: >- Invalid condition. Available conditions: excellent, clean, average, rough invalidMileage: value: success: false message: Invalid mileage. Must be a number "401": $ref: "#/components/responses/Unauthorized" "404": description: No data found for this VIN. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: No data found for this VIN "429": $ref: "#/components/responses/UsageLimitExceeded" "500": $ref: "#/components/responses/InternalServerError" "503": description: Upstream market value provider is unavailable. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Cannot access the internet at this time components: securitySchemes: ApiKeyQuery: type: apiKey in: query name: key description: Your CarsXE API key, passed as the `key` query parameter. X402Payment: type: apiKey in: header name: PAYMENT-SIGNATURE description: >- x402 payment proof for supported operations. Start without a CarsXE key to receive HTTP 402 payment requirements, then retry the identical request with the payment header produced by your x402 client. CarsXE also accepts the legacy X-PAYMENT header. RecallsBatchToken: type: apiKey in: header name: X-CarsXE-Batch-Token description: Batch-scoped token returned by an x402 Recalls Batch submission. parameters: vin: name: vin in: query required: true schema: type: string minLength: 17 maxLength: 17 description: The 17 character long vehicle identification number. format: name: format in: query required: false schema: type: string enum: [json, xml] default: json description: The format of the response. One of `json` or `xml`. batchId: name: batchId in: query required: true schema: type: string description: The batch ID returned from the submit endpoint. recallsBatchToken: name: X-CarsXE-Batch-Token in: header required: false schema: type: string description: >- Batch-scoped token returned by an x402 submit call. Use this instead of the key query parameter for status, results, and download requests. schemas: Error: type: object properties: success: type: boolean const: false message: type: string required: [success, message] additionalProperties: true UsageLimitError: allOf: - $ref: "#/components/schemas/Error" - type: object properties: usage: type: object properties: current: type: number description: Current usage in the billing period. limit: type: number description: Included quota for the billing period. remaining: type: number description: Remaining included quota. SuccessEnvelope: type: object description: >- Generic success envelope. Endpoint-specific payload fields appear at the top level alongside these common fields. properties: success: type: boolean input: type: object description: Echo of the input parameters specified by the query. additionalProperties: true timestamp: type: string additionalProperties: true SpecsResponse: allOf: - $ref: "#/components/schemas/SuccessEnvelope" - type: object properties: attributes: type: object description: >- A map of specifications about the VIN (year, make, model, trim, style, type, size, category, made_in, doors, fuel_type, engine, transmission, drivetrain, dimensions, pricing and more). additionalProperties: true colors: type: array description: >- Available color options based on the vehicle's year, make and model. items: type: object properties: category: type: string name: type: string additionalProperties: true equipment: type: object description: >- Equipment details based on the vehicle's year, make and model. additionalProperties: true warranties: type: array description: Standard vehicle warranties by type, miles and months. items: type: object properties: type: type: string miles: type: string months: type: string additionalProperties: true deepdata: type: object description: >- More information on the vehicle from the deep data search (present when `deepdata=1`). additionalProperties: true responses: Unauthorized: description: >- Missing API key, unknown/disabled API key, or inactive account. content: application/json: schema: $ref: "#/components/schemas/Error" examples: missingKey: value: success: false message: Missing API key userNotFound: value: success: false message: >- User with this API key was not found or the API key is disabled userNotActive: value: success: false message: >- User with this API key is not active. To activate update your billing on https://carsxe.com/dashboard/billing UsageLimitExceeded: description: >- API usage limit exceeded for the current billing period. content: application/json: schema: $ref: "#/components/schemas/UsageLimitError" example: success: false message: API usage limit exceeded usage: current: 1000 limit: 1000 remaining: 0 InternalServerError: description: Internal server error. content: application/json: schema: $ref: "#/components/schemas/Error" example: success: false message: Internal server error