details

Catalog-shaped search alias

A compatibility alias for search with catalog-shaped parameter names. Also served at /listVehicles.

This route is not granted by default: it bypasses the public pagination caps, so it is a deliberate per-key grant.

get/api/listVehicles

Request

  • Base URL: https://api.thecarapi.com
  • URL: https://api.thecarapi.com/api/listVehicles
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer
    • API key in query parameter api_key

Query parameters

manufacturer_slugstring
manufacturerstring
brandstring
model_group_slugstring
model_groupstring
modelstring
fuel_typestring
fuelstring
steering'left' | 'lhd' | 'left-hand' | 'left_hand' | 'right' | 'rhd' | 'right-hand' | 'right_hand'
Example:left

Which side the steering wheel is on. The parameter takes two values, left and right; lhd/left-hand/left_hand and rhd/right-hand/right_hand are equivalent spellings of them. Any other value is a 400.

Derived rather than stored. The side is taken from the car's registration market, so a car from an ISO country that drives on the left (GB, IE, JP, CY, MT, AU, NZ, ZA, IN, TH, HK, SG) is right and everything else is left. Every listing resolves to one side or the other, so the two values partition the inventory and their totals sum to the unfiltered total. The same value is published on each result as steering.

Accepted by /api/search, /api/listVehicles, /api/top-offers and every facet endpoint, which narrow their option lists by it. Sending it to a facet endpoint takes that request off the precomputed facet table and onto a live aggregate, so it is slower than an unfiltered facet call.

orderingstring
Example:-created_at

e.g. -created_at, price, -price, year, -year.

min_yearinteger
max_yearinteger
max_mileageinteger
limitinteger

Page size. Capped at pagination.max_limit from GET /api/contract (100 by default); larger values are clamped down rather than rejected. Do not combine with page_size — that is a 400.

offsetinteger

0-based row offset. Do not combine with page — that is a 400. Bounded by pagination.max_offset (5000 by default) on archive, catalog, top-offers and classifieds; /api/search and /api/listVehicles have no offset cap.

pageinteger

1-based page number; maps to offset = (page - 1) * limit. Do not combine with offset.

page_sizeinteger

Alias for limit. Do not combine with limit.

Response

Matching vehicles. vehicles and results are the same array.

successboolean required
contract_versionstring

Matches info.version of this document.

request_idstring

Also returned as the X-Request-ID header.

server_timestring date-time

UTC ISO-8601 timestamp of the response.

data_updated_atstring date-time

Route-supplied data timestamp, falling back to server_time. Not a guaranteed source refresh time; inspect listing observation timestamps and live_price.fetched_at where available.

totalinteger nullable

null when totals are suppressed or could not be computed.

limitinteger
offsetinteger
pageinteger
page_sizeinteger
total_pagesinteger nullable

null when total is null.

max_pageinteger nullable

Deepest page reachable under the offset policy.

Example response

{
  "success": true,
  "contract_version": "2026-09-03",
  "vehicles": [
    {
      "auction_id": 38112900,
      "site_name": "openlane",
      "clean_make": "BMW",
      "clean_model": "320d",
      "model_display": "320d M Sport",
      "registration_year": 2020,
      "production_year": 2019,
      "production_month": 11,
      "mileage": 45000,
      "fuel_group": "Diesel",
      "gearbox_group": "Automatic",
      "steering": "left",
      "public_price_eur": 21500,
      "auction_end_at": "2026-08-20T10:00:00Z",
      "country_code": "DE",
      "auction_id_str": "38112900"
    }
  ],
  "results": [
    {
      "auction_id": 38112900,
      "site_name": "openlane",
      "clean_make": "BMW",
      "clean_model": "320d",
      "model_display": "320d M Sport",
      "registration_year": 2020,
      "production_year": 2019,
      "production_month": 11,
      "mileage": 45000,
      "fuel_group": "Diesel",
      "gearbox_group": "Automatic",
      "steering": "left",
      "public_price_eur": 21500,
      "auction_end_at": "2026-08-20T10:00:00Z",
      "country_code": "DE",
      "auction_id_str": "38112900"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.