GET /v1/listings/search

Normalized search across listing sources

Search by natural language (q) and/or structured filters. Combines the platform listings cache with a live fan-out to healthy sources (per-source timeout; a failing or blocked source is reported in errors[] and never fails the request). Results are deduplicated across sources and ranked. Requires scope read:listings.

Authentication: header Authorization: Bearer rv_live_... (API keys and scopes)
Required scope: read:listings

Descriptions of the operation, parameters and fields come from the OpenAPI specification (openapi.json).

Parameters

Field	In	Type	Required	Description
`q`	query	`string`	no	Natural-language query, e.g. "BMW X5 2019-2021 up to 35 000 EUR, diesel, under 150k km". Structured params below override what is parsed from q.
`make`	query	`string`	no
`model`	query	`string`	no
`year_from`	query	`integer`	no
`year_to`	query	`integer`	no
`price_min_eur`	query	`number \| null`	no
`price_max_eur`	query	`number \| null`	no
`mileage_max_km`	query	`number \| null`	no
`fuel`	query	`string`	no	Comma-separated: petrol,diesel,hybrid,phev,ev,lpg,cng,hydrogen,other.
`country`	query	`string`	no	Comma-separated ISO-3166 alpha-2 codes of the car location, e.g. DE,PL.
`market`	query	`string`	no	Comma-separated: us,eu,cn,kr,ua,ge.
`sources`	query	`string`	no	Comma-separated source keys to restrict the search to (e.g. mobile_de,otomoto).
`no_accidents`	query	`"true" \| "false"`	no	Exclude salvage/rebuilt/flood titles.
`limit`	query	`integer`	no
`live`	query	`"true" \| "false"`	no	true: also query healthy live sources (slower, bounded by a timeout). false: only the platform cache.

Responses

200

Normalized listings.

application/json · Schema: SearchListingsResponse

Field	Type	Required	Description
`query`	`object`	yes	The structured query that was actually executed.
`query.text`	`string`	no
`query.make`	`string`	no
`query.model`	`string`	no
`query.yearFrom`	`integer`	no
`query.yearTo`	`integer`	no
`query.priceMin`	`object`	no
`query.priceMax`	`object`	no
`query.mileageMaxKm`	`number`	no
`query.fuel`	`"petrol" \| "diesel" \| "hybrid" \| "phev" \| "ev" \| "lpg" \| "cng" \| "hydrogen" \| "other"[]`	no
`query.gearbox`	`"manual" \| "automatic" \| "cvt" \| "robot" \| "other"[]`	no
`query.body`	`"sedan" \| "hatchback" \| "wagon" \| "suv" \| "crossover" \| "coupe" \| "convertible" \| "minivan" \| "van" \| "pickup" \| "truck" \| "motorcycle" \| "other"[]`	no
`query.drive`	`"fwd" \| "rwd" \| "awd" \| "4wd"[]`	no
`query.markets`	`"us" \| "eu" \| "cn" \| "kr" \| "ua" \| "ge"[]`	no
`query.countries`	`string[]`	no
`query.noAccidents`	`boolean`	no
`query.sourceKeys`	`string[]`	no
`query.limit`	`integer`	no
`query.page`	`integer`	no
`query_parser`	`"structured" \| "rules" \| "llm"`	yes	How q was interpreted: structured (no q), rules (rule-based) or llm.
`results`	`object[]`	yes
`results[].sourceKey`	`string`	no
`results[].externalId`	`string`	no
`results[].url`	`string (uri)`	no
`results[].title`	`string`	no
`results[].make`	`string \| null`	no
`results[].model`	`string \| null`	no
`results[].trim`	`string \| null`	no
`results[].year`	`integer \| null`	no
`results[].vin`	`string \| null`	no
`results[].price`	`object`	no
`results[].priceEur`	`number \| null`	no
`results[].priceType`	`"fixed" \| "current_bid" \| "buy_now" \| "estimate" \| "unknown"`	no
`results[].mileageKm`	`number \| null`	no
`results[].fuel`	`"petrol" \| "diesel" \| "hybrid" \| "phev" \| "ev" \| "lpg" \| "cng" \| "hydrogen" \| "other" \| null`	no
`results[].gearbox`	`"manual" \| "automatic" \| "cvt" \| "robot" \| "other" \| null`	no
`results[].drive`	`"fwd" \| "rwd" \| "awd" \| "4wd" \| null`	no
`results[].body`	`"sedan" \| "hatchback" \| "wagon" \| "suv" \| "crossover" \| "coupe" \| "convertible" \| "minivan" \| "van" \| "pickup" \| "truck" \| "motorcycle" \| "other" \| null`	no
`results[].engineCc`	`number \| null`	no
`results[].powerKw`	`number \| null`	no
`results[].batteryKwh`	`number \| null`	no
`results[].color`	`string \| null`	no
`results[].damage`	`object`	no
`results[].titleStatus`	`"clean" \| "salvage" \| "rebuilt" \| "flood" \| "junk" \| "parts_only" \| "certificate" \| "unknown" \| null`	no
`results[].location`	`object`	no
`results[].market`	`"us" \| "eu" \| "cn" \| "kr" \| "ua" \| "ge"`	no
`results[].seller`	`object`	no
`results[].photos`	`string (uri)[]`	no
`results[].auction`	`object`	no
`results[].listedAt`	`string \| null (date-time)`	no
`results[].fetchedAt`	`string (date-time)`	no
`results[].completeness`	`number`	no
`results[].details`	`object`	no
`results[].sources`	`object[]`	no	All sources where this car was found (deduplicated by VIN / photo / fuzzy match).
`results[].score`	`number`	no	Rank score 0..1 (data completeness, freshness, multi-source confirmation).
`total`	`integer`	yes	Number of deduplicated results before the limit was applied.
`sources`	`object`	yes
`sources.cache`	`object`	yes
`sources.live`	`object`	yes
`errors`	`object[]`	yes	Per-source problems. A failing source never fails the whole search.
`errors[].source_key`	`string`	no
`errors[].code`	`"timeout" \| "blocked" \| "failed" \| "unhealthy" \| "aborted"`	no
`errors[].message`	`string`	no
`errors[].blocked_reason`	`string`	no
`took_ms`	`integer`	yes