---
title: "Versioning & Migration"
description: "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."
canonical_url: "https://docs.carsxe.com/docs/guides/versioning"
markdown_url: "https://docs.carsxe.com/docs/guides/versioning.md"
last_updated: "1980-01-01"
x_farming_labs_generated_preamble: true
agent:
  task: "Migrate a CarsXE integration from a v1 endpoint to its v2 equivalent."
  outcome: "The client calls the v2 path with the v2 required parameters and parses the v2 response shape without breaking remaining v1 endpoints."
  appliesTo:
    version:
      - "CarsXE API v1 and v2"
  prerequisites:
    - "A valid CarsXE API key."
    - "The current v1 path and response fields the client already parses."
    - "The target v2 product guide (Plate Decoder or Market Value) for field mapping."
  verification:
    - "Plate Decoder migration uses GET /v2/platedecoder with a required country parameter and no longer depends on v1 field names such as Description or CarMake."
    - "Market Value migration uses GET /v2/marketvalue, drops the format parameter, and reads per-condition objects instead of a single retail figure."
    - "Remaining v1 endpoints still succeed after the per-endpoint cutover; v1 is not turned off by shipping v2."
  failureModes:
    - symptom: "A v2 Plate Decoder request returns a validation error."
      resolution: "Always send country (ISO 3166-1 alpha-2). v1 treated country as optional and defaulted to US behavior."
    - symptom: "Response parsing fails after the URL change."
      resolution: "Remap fields against the v2 examples on the product page; do not reuse v1 names or nesting."
    - symptom: "A Spanish plate request is billed twice unexpectedly."
      resolution: "require_vin=true is billed 2× and counts 2× toward usage — remove it unless a VIN is required."
    - symptom: "Production traffic was switched before tests passed."
      resolution: "Keep v1 in place, rerun integration tests against the v2 paths, then cut over per endpoint."
---

# Versioning & Migration
URL: /docs/guides/versioning
LLM index: /llms.txt
Description: 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.
Related: /docs/get-started, /docs/products/plate-decoder, /docs/products/market-value, /docs/guides/errors

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Migrate a CarsXE integration from a v1 endpoint to its v2 equivalent.
Outcome: The client calls the v2 path with the v2 required parameters and parses the v2 response shape without breaking remaining v1 endpoints.

### Applies To

- Version: `CarsXE API v1 and v2`

### Prerequisites

- A valid CarsXE API key.
- The current v1 path and response fields the client already parses.
- The target v2 product guide (Plate Decoder or Market Value) for field mapping.

### Verification

- Plate Decoder migration uses GET /v2/platedecoder with a required country parameter and no longer depends on v1 field names such as Description or CarMake.
- Market Value migration uses GET /v2/marketvalue, drops the format parameter, and reads per-condition objects instead of a single retail figure.
- Remaining v1 endpoints still succeed after the per-endpoint cutover; v1 is not turned off by shipping v2.

### Failure Modes

- A v2 Plate Decoder request returns a validation error. — Recovery: Always send country (ISO 3166-1 alpha-2). v1 treated country as optional and defaulted to US behavior.
- Response parsing fails after the URL change. — Recovery: Remap fields against the v2 examples on the product page; do not reuse v1 names or nesting.
- A Spanish plate request is billed twice unexpectedly. — Recovery: require_vin=true is billed 2× and counts 2× toward usage — remove it unless a VIN is required.
- Production traffic was switched before tests passed. — Recovery: Keep v1 in place, rerun integration tests against the v2 paths, then cut over per endpoint.
<!-- farming-labs:agent-contract:end -->

Task: Migrate a CarsXE integration from a v1 endpoint to its v2 equivalent.

Prerequisites:
- A valid CarsXE API key.
- The current v1 path and response fields the client already parses.
- The target v2 product guide (Plate Decoder or Market Value) for field mapping.

Outcome: The client calls the v2 path with the v2 required parameters and parses the v2 response shape without breaking remaining v1 endpoints.

Verification:
- Plate Decoder migration uses `GET /v2/platedecoder` with a required `country` parameter and no longer depends on v1 field names such as `Description` or `CarMake`.
- Market Value migration uses `GET /v2/marketvalue`, drops the `format` parameter, and reads per-condition objects instead of a single `retail` figure.
- Remaining v1 endpoints still succeed after the per-endpoint cutover; v1 is not turned off by shipping v2.

Related: /docs/guides/versioning, /docs/products/plate-decoder, /docs/products/market-value

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.

## How versioning works

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:

- **Versions run side by side.** Shipping v2 does not turn off v1. There is currently no retirement date for any v1 endpoint; if one is ever scheduled, it will be announced well in advance.
- **Responses can gain fields.** Within a version we may add new fields to responses as data coverage improves. Build clients that ignore unknown fields — never fail on properties you don't recognize.
- **Breaking changes get a new path.** Changed parameter semantics or response shapes only ever ship under a new version prefix.

<Note>
  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.
</Note>

## OpenAPI specification

A machine-readable OpenAPI 3.1 spec covering every public endpoint (v1 and v2) is available at:

<PortableCode value={{
 language: "bash",
 code: `curl -O https://api.carsxe.com/openapi.yaml`
}} />

Import it into Postman, Insomnia, or your code generator of choice to get typed clients and a request collection without writing anything by hand.

## What's new in v2

### Plate Decoder

[Product guide](/docs/products/plate-decoder) · [v1 reference](/api-reference/plate-decoder/license-plate-decoder-v1) · [v2 reference](/api-reference/plate-decoder/license-plate-decoder-v2)

| | 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 product guide |

**Migration steps:**

1. Change the URL from `/platedecoder` to `/v2/platedecoder`.
2. Always pass `country` (ISO 3166-1 alpha-2, e.g. `US`, `ES`, `PK`). In v1, `country` was optional and defaulted to US behavior. See [Supported Countries](/docs/guides/supported-countries) for valid values.
3. Update your response parsing — field names and nesting differ. Compare your target countries' example responses on the [Plate Decoder](/docs/products/plate-decoder) page against what you parse today.
4. If you need a VIN for Spanish plates, add `require_vin=true` and account for the 2× billing.

### Market Value

[Product guide](/docs/products/market-value) · [v1 reference](/api-reference/market-value/vehicle-market-value-v1) · [v2 reference](/api-reference/market-value/vehicle-market-value-v2)

| | 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](/docs/products/market-value) |

**Migration steps:**

1. Change the URL from `/marketvalue` to `/v2/marketvalue`.
2. Pass `mileage` and `condition` when you have them — v2 valuations adjust for both, which is the main accuracy win.
3. Map your fields: where v1 gave a single `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).
4. Drop the `format` parameter — v2 responds in JSON only.

## Error-handling differences

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](/docs/guides/errors) for the complete catalog.

Quota errors (`429`) behave identically on both versions and include the `usage` object — see [Rate Limits & Quotas](/docs/guides/rate-limits).

## Migration checklist

- [ ] Swap URLs to the `/v2/` paths for the endpoints you're migrating
- [ ] Pass `country` on every Plate Decoder request
- [ ] Update response parsing against the v2 example responses for your markets
- [ ] Send `mileage` and `condition` to Market Value where available
- [ ] Make response parsing tolerant of unknown fields
- [ ] Re-run your integration tests against the v2 endpoints before switching production traffic

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).