Getting started

A REST API over normalized auction inventory from Auto1, OpenLane, Schadeautos, Copart Germany, eCarsTrade, Encar and the Japanese auction houses, plus a European retail classifieds network. Every response is JSON, every read is a GET, and the only required credential is an API key in a header.

This reference covers the stable customer integration surface and nothing else. Website-only helpers and internal publishing operations exist but are not public, are not versioned for you, and are not documented here.

The mental model

A vehicle is addressed by the pair site_name + auction_id — for example encar/38112900. That pair is stable for the life of the listing and is the only identifier you need to persist. Everything else in the API is either a way of finding that pair (search, facets, catalog, top offers) or a way of expanding it (detail, images, price history, VIN history).

1. 1Discover. /api/search with filters, or /api/facets to populate the filter controls themselves. You get result cards carrying site_name and auction_id.
2. 2Expand. /api/auction/{site}/{id} returns the full record for one card — specification, condition, the normalized vehicle_details block, and the image gallery embedded as vault_gallery.
3. 3Enrich. Price history, VIN history, market reference prices and the landed-cost calculator all take the same pair, or figures from the detail response.

Base URL

https://api.thecarapi.com

HTTPS is required; plain HTTP is refused rather than redirected. Send JSON request bodies with Content-Type: application/json. There is no URL version prefix — the schema contract is carried in the contract_version field of every response and declared in full by /api/contract.

Your first request

curl -sS \
  -H "X-API-Key: $API_KEY" \
  -H "Accept-Encoding: gzip" \
  --compressed \
  "https://api.thecarapi.com/api/search?brand=bmw&fuel=Diesel&year_from=2018&sort=price_low&limit=24"

A successful response carries success: true, the payload under a route-specific key, and the correlation fields described in Responses & pagination. Store request_id — it is the only thing that lets support trace a specific call.

Anatomy of a request

What this API is not

• Not a bidding interface. It observes auction prices; it never places, raises or withdraws a bid, and it grants no purchase rights on any source platform.
• Not a fee quote. Auction fees, transport and delivery figures are quoted to our buyer account and our address, so they are stripped at the response boundary. Use the import calculator for landed cost on your own route.
• Not a file host for source paperwork. Inspection reports and documents are returned as links to the auction house; they are never proxied or stored, and upstream links expire.

Read these before you render anything

Three pages answer the questions that cause the most rework, and all three are about what the data means rather than how to request it.