Getting started

A REST API over normalized auction inventory from Auto1, OpenLane, Schadeautos, Copart Germany, eCarsTrade, Encar, KB ChaChaCha and the Japanese auction houses, plus a European retail classifieds network of some 680 portals. Data responses are JSON, and reads use 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_str — 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_str.
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 most responses (see Responses & pagination for the handful that omit it) 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

Responses may also carry X-Perf-* and X-Local-Source headers. Those are diagnostic, are not part of this contract, and may change or disappear without notice — do not branch on them.

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.
• Report files are served through the API. Normalized document and report URLs use /report-vault paths. Files are fetched and cached; unsupported hosts or non-file pages can redirect to the source.

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.