CarsXE

The @carsxe/sdk package is the official CarsXE client for Node.js and TypeScript. It wraps the REST API with typed methods, handles authentication, and throws structured errors. Requires Node.js 18 or later.

Installation

npm install @carsxe/sdk
# yarn add @carsxe/sdk
# pnpm add @carsxe/sdk
# bun add @carsxe/sdk

Quick start

Decode a VIN

import { CarsXE } from '@carsxe/sdk'

const carsxe = new CarsXE({ apiKey: process.env.CARSXE_API_KEY! })

const result = await carsxe.decodeVin('WBAFR7C57CC811956')
console.log(result.data.make, result.data.model, result.data.year)

Methods

Core

MethodDescription
decodeVin(vin)Decode a 17-character VIN into full vehicle specifications
getMarketValue(params)Retail, trade-in, and auction value estimates
getRecalls(params)Open safety recalls by VIN, make, model, or year
decodePlate(params)VIN lookup from a license plate (50+ countries)
getVehicleHistory(vin)Title events, salvage, junk, and insurance records

Bulk recall batch

MethodDescription
submitBulkRecallBatch(params)Submit a batch of VINs for recall lookup
getBulkRecallBatchStatus(batchId)Poll job status
getBulkRecallBatchResults(batchId)Retrieve completed results
getBulkRecallBatchDownloadUrl(batchId)Get a CSV download URL

Error handling

All methods throw on non-2xx responses. Wrap calls in try/catch:

import { CarsXE } from '@carsxe/sdk'

const carsxe = new CarsXE({ apiKey: process.env.CARSXE_API_KEY! })

try {
  const result = await carsxe.decodeVin('WBAFR7C57CC811956')
  console.log(result.data)
} catch (err) {
  // err.statusCode, err.code, err.message
  console.error('CarsXE error:', err)
}

Best practices

Create one instance and reuse it. The client reuses the underlying fetch connection pool — instantiating per-request wastes resources.

// lib/carsxe.ts
import { CarsXE } from '@carsxe/sdk'

export const carsxe = new CarsXE({ apiKey: process.env.CARSXE_API_KEY! })

Store your key in an environment variable. Never hardcode it or commit it to source control.

# .env
CARSXE_API_KEY=your_key_here

TypeScript types are included. The package ships full .d.ts declarations — no @types package needed. All response shapes (VehicleSpec, MarketValue, Recall, etc.) are exported directly from @carsxe/sdk.