How CarsXE versions its API, what changed between v1 and v2, and a step-by-step guide for migrating the Plate Decoder and Market Value endpoints.
CarsXE versions the API in the URL path, so a version you build against keeps behaving the way it did when you shipped. This page explains the versioning rules, what's new in v2, and exactly what to change when you migrate.
There are three URL patterns, reflecting when each endpoint family was introduced:
| Pattern | Example | What lives there |
|---|---|---|
| Root paths | https://api.carsxe.com/specs | The original v1 APIs (Specifications, Market Value, Plate Decoder, History, Images, and others). |
/v1/... | https://api.carsxe.com/v1/recalls-batch/submit | Newer additions to the v1 generation (Recalls, Recalls Batch, Lien & Theft, VIN OCR, Year Make Model, International VIN Decoder). |
/v2/... | https://api.carsxe.com/v2/platedecoder | The current generation. New capabilities ship here. |
A few things you can rely on:
Migrating is opt-in and per-endpoint. You can move Plate Decoder to v2 today and leave Market Value on v1 — there is no flag day.
A machine-readable OpenAPI 3.1 spec covering every public endpoint (v1 and v2) is available at:
curl -O https://api.carsxe.com/openapi.yamlImport it into Postman, Insomnia, or your code generator of choice to get typed clients and a request collection without writing anything by hand.
| v1 | v2 | |
|---|---|---|
| URL | GET /platedecoder | GET /v2/platedecoder |
| Required params | plate, state (US) | plate, country |
| Region params | state, country | state where applicable, plus country-specific params (e.g. district for Pakistan) |
| Coverage | Core countries | Expanded country coverage, documented per country with examples |
| VIN guarantee | — | require_vin=true (Spain) always returns a VIN. Billed 2× and counts 2× toward usage. |
| Response shape | Flat fields (Description, CarMake, CarModel, …) | Restructured per-country response — see the per-country examples in the v2 docs |
Migration steps:
/platedecoder to /v2/platedecoder.country (ISO 3166-1 alpha-2, e.g. US, ES, PK). In v1, country was optional and defaulted to US behavior.require_vin=true and account for the 2× billing.| v1 | v2 | |
|---|---|---|
| URL | GET /marketvalue | GET /v2/marketvalue |
| Required params | vin | vin |
| Optional params | format | state, mileage, condition (excellent, clean, average, rough) |
| Valuation model | Single retail/trade-in figures | Wholesale, retail, and trade-in breakdowns per condition tier, with base, mileage, regional, and add/deduct adjustments |
| Response shape | retail, tradeIn, loanValue, msrp, auctionValues, … | whole_*, retail_*, trade_in_* objects per condition — see response attributes |
Migration steps:
/marketvalue to /v2/marketvalue.mileage and condition when you have them — v2 valuations adjust for both, which is the main accuracy win.retail figure, v2 gives retail_xclean / retail_clean / retail_avg / retail_rough objects. Pick the tier matching the vehicle's condition (or use condition to let the API adjust).format parameter — v2 responds in JSON only.v2 endpoints use precise HTTP status codes for every failure mode. A few legacy v1 routes return 500 for what are really validation errors (for example, missing make/model on the Images API), so v1 clients should check the success field in the body rather than relying on status codes alone. See the error reference for the complete catalog.
Quota errors (429) behave identically on both versions and include the usage object — see Rate Limits & Quotas.
/v2/ paths for the endpoints you're migratingcountry on every Plate Decoder requestmileage and condition to Market Value where available