canonical: https://jentic.com/apis/carsxe.com/carsxe

# CarsXE Vehicle Data API

CarsXE Vehicle Data API exposes a suite of vehicle intelligence services across nine endpoints: VIN-based specifications, international VIN decoding, license plate decoding (v1 and v2), market value estimation, recall lookup, vehicle history, vehicle images, and VIN OCR from a photo. It serves automotive marketplaces, dealerships, insurers, and used-car buyers that need to validate, value, and visualise a vehicle from a VIN, plate, or image. Authentication is an API key passed as the `key` query parameter.

## For AI agents

Decode VINs and plates internationally, value vehicles, pull recalls and history reports, fetch images, and OCR a VIN from a photo via nine endpoints.

## Scope

Does not handle vehicle telematics, real-time location, or insurance quoting - use for VIN/plate decoding, market value, recalls, history, images, and VIN OCR only.

## Capabilities

- Get full vehicle specifications from a VIN, including international VINs
- Resolve a license plate to its vehicle record (v1 GET or v2 POST flow)
- Estimate the market value of a vehicle for valuation and pricing flows
- Look up open and historical recalls by VIN
- Pull a vehicle history report by VIN
- Retrieve vehicle images by VIN for listing pages and condition reporting
- Run VIN OCR on a submitted photo to extract the 17-character VIN

## Use cases

### Used Car Marketplace Listing Enrichment

Enrich every used car listing with VIN-decoded specifications, current market value, recall status, and stock images. The CarsXE endpoints together cover the full enrichment pipeline: GET `/v1/specifications` and POST `/v2/market-value` populate the listing card, GET `/v1/vehicle-recalls` highlights safety concerns, and GET `/v1/images` provides visuals when seller photos are missing.

Example prompt: For VIN 1HGCM82633A123456, fetch specifications, market value, and recalls, then return a listing-ready summary.

### Insurance Underwriting Vehicle Lookup

Power an insurance quote engine that needs full vehicle context from a VIN or plate. `/v1/specifications` returns make, model, year, body, and engine; `/v1/history` returns prior accident and ownership context; `/v1/vehicle-recalls` flags outstanding safety items. Plate decoding (v1 GET or v2 POST) lets the agent start from a plate when the policyholder has not provided the VIN.

Example prompt: Given plate ABC1234 in CA, decode it to a VIN, then fetch specifications and history and return a structured underwriting record.

### VIN Capture from Photo with OCR

Let users submit a photo of a vehicle's dashboard or door jamb and have the API extract the VIN automatically. POST `/v1/vin-ocr` accepts an image and returns the parsed VIN string, which can then be passed into the other CarsXE endpoints to retrieve specifications, recalls, history, and value in a single workflow.

Example prompt: Upload a dashboard photo to `/v1/vin-ocr`, take the returned VIN, and call `/v1/specifications` on it.

### AI Agent Vehicle Intelligence via Jentic

Plug CarsXE into an agent through Jentic so a question like 'tell me everything about this VIN' triggers a coordinated set of calls behind a single tool surface. Jentic returns each operation's schema, holds the API key in its vault, and lets the agent chain VIN decoding, market value, and recall lookups without managing the URL key parameter.

Example prompt: Through Jentic, decode VIN 1HGCM82633A123456, fetch market value, and return a one-paragraph summary.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/specifications` | Get vehicle specifications by VIN |
| GET | `/v1/international-vin-decoder` | Decode an international VIN |
| GET | `/v1/plate-decoder` | Decode a license plate (v1) |
| POST | `/v2/plate-decoder` | Decode a license plate (v2) |
| POST | `/v2/market-value` | Get vehicle market value |
| GET | `/v1/vehicle-recalls` | Get vehicle recalls by VIN |
| GET | `/v1/history` | Get vehicle history report |
| POST | `/v1/vin-ocr` | Extract VIN from a photo |

## Key resources

- **Specifications** — VIN-based vehicle specifications and international VIN decoding
- **Plate Decoder** — Resolve a license plate to vehicle record via v1 GET or v2 POST endpoints
- **Market Value** — Estimate current market value for a given vehicle
- **Recalls** — Look up open and historical recalls by VIN
- **History** — Retrieve vehicle history reports by VIN
- **Images** — Fetch vehicle images by VIN
- **VIN OCR** — Extract a VIN from a submitted photo

## Why Jentic

- **Setup:** Wiring the CarsXE Vehicle Data API by hand means passing your key in the key query parameter on every call and threading requests across the v1 and v2 routes on the api.carsxe.com host yourself. Through Jentic you install once, import the CarsXE Vehicle Data API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** CarsXE routes each lookup by its own path, so you scope by operation: limit the agent to the ones it needs, such as decoding a VIN or fetching market value, and leave plate decoding or VIN OCR out of the allowed set until you want them.
- **Credential handling:** Your CarsXE API key is stored once, encrypted, by your own Jentic One instance and injected into the key query parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'decode a VIN' or 'get vehicle market value', and Jentic returns the matching CarsXE operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **CarAPI.dev** — Automotive data API focused on Central Europe with VIN, valuation, and stolen-vehicle checks.
- **Carrier Lookup** — Phone number carrier lookup useful for verifying seller contact details.
- **CarbonAPI** — Calculates emissions for products and journeys, including vehicles.

## FAQ

### What authentication does the CarsXE Vehicle Data API use?

CarsXE uses an API key passed as the `key` query parameter on every request. Through Jentic the key is stored encrypted in the credential vault and injected at request time, so the raw key never enters the agent's prompt or chat history.

### What's the difference between the v1 and v2 plate decoder endpoints?

GET `/v1/plate-decoder` is the legacy endpoint that takes plate and state as query parameters. POST `/v2/plate-decoder` is the newer flow that accepts a JSON body and supports a richer parameter set. New integrations should default to v2; v1 remains for backwards compatibility.

### Can CarsXE decode VINs registered outside the United States?

Yes. GET `/v1/international-vin-decoder` is dedicated to non-US VINs and returns make, model, year, and trim details for international registrations. Use GET `/v1/specifications` for US-registered VINs where the standard specification dataset applies.

### How do I extract a VIN from a photo with CarsXE?

Submit the image to POST `/v1/vin-ocr`; the response contains the parsed 17-character VIN string. Pass that VIN into GET `/v1/specifications`, GET `/v1/vehicle-recalls`, or GET `/v1/history` to chain the OCR result into a full vehicle intelligence workflow.

### What are the rate limits for the CarsXE API?

The OpenAPI specification does not declare numeric rate limits. CarsXE applies per-key throttling at its gateway based on plan tier; if you receive 429 responses, slow concurrency and check the dashboard at https://api.carsxe.com/docs for the limits attached to your account.

### How do I value a vehicle through Jentic?

Run `pip install jentic`, then use Jentic's search to find the market-value operation with the query "get vehicle market value", load the schema, and execute with `{"vin": "1HGCM82633A123456"}`. Jentic posts to `/v2/market-value` with your CarsXE key from the vault and returns the estimated value as structured output.

### Does CarsXE return vehicle images?

Yes. GET `/v1/images` takes a VIN and returns a set of image URLs for that vehicle, useful for listing pages or condition reporting when seller-supplied photos are missing or low quality.

### Can I limit what my agent is allowed to do with the CarsXE Vehicle Data API?

Yes. Because CarsXE routes each lookup by its own path, your self-hosted Jentic One instance lets you scope access per operation, and your own rules decide which endpoints and credentials the agent may use. You can allow only the calls you need, such as VIN specifications via GET `/v1/specifications` or market value via POST `/v2/market-value`, while leaving plate decoding and VIN OCR out of the allowed set. The agent can invoke only the operations you permit, and your CarsXE key is injected at execution time rather than exposed to the model.