---
title: "Getting started"
description: "What the API serves, the two datasets it exposes, the shape of a request, and a first call you can paste into a terminal."
canonical: "https://thecarapi.com/docs"
contract_version: "2026-08-19"
api_base: "https://api.thecarapi.com"
source: "https://thecarapi.com/docs.md"
---

# Getting started

What the API serves, the two datasets it exposes, the shape of a request, and a first call you can paste into a terminal.

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. **Discover.** `/api/search` with filters, or `/api/facets` to populate the filter controls themselves. You get result cards carrying `site_name` and `auction_id`.
2. **Expand.** `/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. **Enrich.** Price history, VIN history, market reference prices and the landed-cost calculator all take the same pair, or figures from the detail response.

> **Every source is priced live** — All seven auction sources refresh continuously rather than on a batch schedule, so every price you read — on a search card, a facet, a top-offer row or a detail response — is a current figure. There is no stale tier and no premium real-time upgrade. Running auctions with open bidding get a further re-read of the current bid at the moment you request the detail; see [Live prices](https://thecarapi.com/docs/live-prices).

> **Two datasets, two surfaces** — Auction inventory is queried through `/api/search` with a `site` slug. The classifieds network is retail listings — no bidding, no end date, no detail payload — so it is never merged into the auction feed, never appears in `/api/sites`, and is queried through `/api/theparking/*` instead.

## Base URL

```text
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](https://thecarapi.com/docs/ops).

## Your first request

```bash
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"
```

_Every documented endpoint takes the same header. `--compressed` is worth having from the first call — see Responses & pagination._

A successful response carries `success: true`, the payload under a route-specific key, and the correlation fields described in [Responses & pagination](https://thecarapi.com/docs/conventions). Store `request_id` — it is the only thing that lets support trace a specific call.

## Anatomy of a request

| Header | Value | Why |
| --- | --- | --- |
| `X-API-Key` | Your key | Required. One auth method per request. |
| `Accept-Encoding` | `gzip` | Responses over 2 KB come back gzipped — roughly an eighth of the bytes on a full search page. |
| `If-None-Match` | A previously received `ETag` | Unchanged pages answer `304` with no body. |
| `Content-Type` | `application/json` | Only for the routes that accept a POST body. |

| Response header | Meaning |
| --- | --- |
| `X-Request-ID` | Correlation id, mirrored in the body as `request_id`. Log it. |
| `ETag` | Weak validator for conditional requests. |
| `X-Cache` | `HIT`, `MISS` or `STALE`. |
| `X-RateLimit-Limit` / `-Remaining` / `-Reset` | Quota state for the current window. |
| `Retry-After` | Sent with `429`. Wait this long, do not guess. |
| `X-Live-Price` | `pending` when a bid refresh missed the request budget. |
| `X-Details-Fetch` | Set while `/api/car-details` is still fetching upstream. |

## 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](https://thecarapi.com/docs/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.

| Page | The question it answers |
| --- | --- |
| [Fields by source](https://thecarapi.com/docs/fields-by-source) | Which of the seven sources actually publishes damages, service history, documents and equipment — and which do not. Read this before you promise a feature. |
| [CO2 & emissions](https://thecarapi.com/docs/co2) | Why there are two CO2 fields, why an estimate always ships with a test standard attached, and why a 2019 figure is not comparable with a 2022 one. |
| [Live prices](https://thecarapi.com/docs/live-prices) | Every source is priced live. How the continuous feed works, the extra at-request bid re-read on open-bidding auctions, and why an absent `live_price` block never means a stale price. |

> **Reading this reference with an agent** — Every page here is available as Markdown, plain text and JSON, and the whole endpoint surface as an OpenAPI 3.1 document. See [Agents & machine formats](https://thecarapi.com/docs/agents).