# TheCarApi — API documentation > Contract 2026-08-19. Base URL https://api.thecarapi.com. 38 public endpoints. > Auth: `X-API-Key: ` or `Authorization: Bearer `. Responses are JSON. > A vehicle is addressed by the pair `site_name` + `auction_id`, e.g. `encar/38112900`. > Price fields are JSON numbers, never strings. ## Sections - [Getting started](https://thecarapi.com/docs.md): What the API serves, the two datasets it exposes, the shape of a request, and a first call you can paste into a terminal. - [Authentication & scopes](https://thecarapi.com/docs/authentication.md): Three interchangeable ways to present a key, the restrictions a key can carry, and the scope groups that gate each endpoint. - [Responses & pagination](https://thecarapi.com/docs/conventions.md): The response envelope, caching and conditional requests, compression, pagination aliases, and rate-limit headers. - [Errors & limits](https://thecarapi.com/docs/errors.md): Status codes, the error body shape, and which failures are worth retrying. - [Sources & site slugs](https://thecarapi.com/docs/sources.md): The `site` slug vocabulary, what each source publishes, and why the classifieds network is not one of them. - [Fields by source](https://thecarapi.com/docs/fields-by-source.md): What each of the seven auction sources actually publishes — the condition-data coverage matrix, the source-specific traps, and how to write code that survives the differences. - [CO2 & emissions](https://thecarapi.com/docs/co2.md): The difference between the measured and estimated CO2 fields, the NEDC/WLTP split that makes a standard tag mandatory, which sources publish a figure, and how to render it without overclaiming. - [Live prices](https://thecarapi.com/docs/live-prices.md): Every source is priced live. How the continuous feed works, the extra at-request bid re-read on open-bidding auctions, and how to read `live_price` and `live_price_pending`. - [Data dictionary](https://thecarapi.com/docs/schema.md): Search card and auction detail field lists, the normalized `vehicle_details` block, per-source coverage, and what is never exposed. - [Search & discovery](https://thecarapi.com/docs/search.md): Search live and archived auction inventory, then resolve lightweight full-text matches. - [Filter facets](https://thecarapi.com/docs/facets.md): Discover live filter values and counts. Facet responses cache for about 600 seconds. A filter sidebar can read every flat dimension in one call with /api/facets. - [Catalog](https://thecarapi.com/docs/catalog.md): Build slug-addressable manufacturer and model-group navigation. - [Auctions & history](https://thecarapi.com/docs/auctions.md): Retrieve source-aware listing detail, galleries, price changes, and VIN history. A running openlane or ecarstrade auction has its bid refreshed from the auction house while the request is served — nothing needs to be passed to enable it. - [Vehicle details](https://thecarapi.com/docs/car-details.md): Fetch a full source payload from cache or, when needed, from the upstream source. - [Top offers](https://thecarapi.com/docs/top-offers.md): Live auctions our pipeline judged to be priced below their market reference. Same deals as /api/search?sort=top_offers, but each card additionally carries the reference the verdict was made against. - [European classifieds](https://thecarapi.com/docs/theparking.md): A retail price surface of roughly 9.8M live listings gathered from 681 origin portals — national classifieds sites, dealer groups and manufacturer stock pages — across 39 European countries: mobile.de, kleinanzeigen.de, autoscout24, leboncoin.fr, lacentrale.fr, autosupermarket.it, njuskalo.hr and hundreds more. Every listing keeps its origin portal in source_site, so the same feed answers a national question and a portal-level one. These are retail listings, not auction inventory: no bidding, no auction end date, no detail payload and no gallery, just a single remote thumbnail per listing. They live in their own tables with their own vocabulary (seller type, origin portal), which is why they get their own query surface instead of a site slug on /api/search. Ended and paid-placement ("promoted") rows are excluded from every response, and all three endpoints return 503 while the dataset has not been built yet. Scope: theparking — that is the scope name in the path, not the name of a source. - [Market intelligence](https://thecarapi.com/docs/market.md): Precomputed price snapshots for a brand, model, and year window. - [Import calculator](https://thecarapi.com/docs/calculator.md): Estimate the landed cost of importing a vehicle. These are estimates, not a binding quote. - [SEO helpers](https://thecarapi.com/docs/seo.md): Build popular landing pages and resolve brand/model URL slugs. - [Health & contract](https://thecarapi.com/docs/ops.md): Check service dependencies and inspect the API index. - [Code examples](https://thecarapi.com/docs/code-examples.md): Minimal clients in cURL, TypeScript, Python and PHP, plus recipes for pagination, conditional requests and detail pages. - [Agents & machine formats](https://thecarapi.com/docs/agents.md): Every page of this reference as Markdown, plain text, JSON and OpenAPI 3.1 — and how to point a coding agent at it. ## Whole reference - [Markdown](https://thecarapi.com/docs/thecarapi-api-reference.md) - [Plain text](https://thecarapi.com/docs/thecarapi-api-reference.txt) - [JSON](https://thecarapi.com/docs/thecarapi-api-reference.json) - [OpenAPI 3.1](https://thecarapi.com/openapi.json) ## Notes for agents - Read `/api/contract` once at startup: it declares the schema surface, pagination caps and which sources support live prices. Do not hardcode source lists or limits. - Retry `429` and `503` honouring `Retry-After`. Never retry `400`, `401`, `403` or `404`. - An absent `live_price` block is the normal case, not an error. - Send `Accept-Encoding: gzip`, and echo `ETag` back as `If-None-Match` when polling.