API reference
GET /v1/catalog/search
Search the EU used-car catalogue (natural language and/or filters)
Search the EU used-car catalogue (natural language and/or filters)
Searches the continuously crawled catalogue of European listings (deduplicated across sites, prices in EUR, landed cost in Ukraine without delivery, deal score). Pass text (natural language) and/or structured filters; structured filters override what was parsed from text. Returns cards, the executed query, how text was understood and a link to the same search on the tenant public site catalogue. 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 |
|---|---|---|---|---|
text | query | string | no | Natural-language query. Structured parameters below override what is parsed from text. |
make | query | string | no | Comma-separated make slugs, e.g. bmw,audi. |
model | query | string | no | Comma-separated "<make>/<model>" slugs, e.g. bmw/x5,volkswagen/golf. |
year_from | query | integer | no | |
year_to | query | integer | no | |
price_from_eur | query | integer | null | no | |
price_to_eur | query | integer | null | no | |
mileage_from_km | query | integer | null | no | |
mileage_to_km | query | integer | null | no | |
power_from_kw | query | integer | null | no | |
power_to_kw | query | integer | null | no | |
fuel | query | string | no | Comma-separated: petrol,diesel,hybrid,phev,ev,lpg,cng,hydrogen,other. |
gearbox | query | string | no | Comma-separated: manual,automatic,cvt,robot,other. |
body | query | string | no | Comma-separated: sedan,hatchback,wagon,suv,crossover,coupe,convertible,minivan,van,pickup,... |
drive | query | string | no | Comma-separated: fwd,rwd,awd,4wd. |
color | query | string | no | Comma-separated: black,white,grey,silver,blue,red,green,brown,beige,yellow,orange,other. |
country | query | string | no | Comma-separated lowercase ISO-3166 codes of EU catalogue markets, e.g. de,nl,be. |
seller | query | string | no | Comma-separated: dealer,private. |
vat | query | string | no | deductible (VAT reclaimable, net price available) and/or included (margin scheme). |
posted_within_days | query | integer | no | |
sort | query | "relevance" | "newest" | "price_asc" | "price_desc" | "mileage_asc" | "year_desc" | "landed_asc" | "deal_score" | no | |
locale | query | "uk" | "pl" | "en" | no | Language of chip labels. |
page | query | integer | no | |
page_size | query | integer | no |
Responses
200
Catalogue search result.
application/json · Schema: CatalogSearchResponse
| Field | Type | Required | Description |
|---|---|---|---|
query | object | yes | Filters that were actually executed. |
query.q | string | no | |
query.make | string[] | no | |
query.model | string[] | no | |
query.yearFrom | integer | null | no | |
query.yearTo | integer | null | no | |
query.priceFrom | integer | null | no | |
query.priceTo | integer | null | no | |
query.mileageFrom | integer | null | no | |
query.mileageTo | integer | null | no | |
query.powerFrom | integer | null | no | |
query.powerTo | integer | null | 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.color | string[] | no | |
query.country | "de" | "at" | "nl" | "be" | "lu" | "fr" | "dk" | "se" | "no" | "fi" | "ee" | "lv" | "lt" | "pl" | "cz" | "sk" | "it" | "es"[] | no | |
query.source | string[] | no | |
query.sellerType | "dealer" | "private" | "unknown"[] | no | |
query.vat | "deductible" | "included" | "unknown"[] | no | |
query.withPhotos | boolean | null | no | |
query.postedWithinDays | integer | null | no | |
query.features | "tow_hitch" | "heat_pump" | "panorama_roof" | "apple_carplay" | "android_auto" | "camera" | "camera_360" | "heated_seats" | "heated_steering" | "ventilated_seats" | "head_up" | "adaptive_cruise" | "navigation" | "keyless" | "electric_tailgate" | "leather"[] | no | |
query.batteryFrom | integer | null | no | |
query.batteryTo | integer | null | no | |
query.sort | "relevance" | "newest" | "price_asc" | "price_desc" | "mileage_asc" | "year_desc" | "landed_asc" | "deal_score" | no | |
parsed | object | yes | How text was understood (null when no text was sent). |
parsed.query | object | yes | Catalog filters (contract catalog-search). Prices are EUR, mileage km, power kW. |
parsed.chips | object[] | yes | What was understood, in reading order. |
parsed.understood | boolean | yes | At least one filter (or a sort) was recognised. |
parsed.method | "rules" | "ai" | "ai_cache" | yes | rules — deterministic parser; ai — Claude (merged with rules); ai_cache — cached model parse. |
parsed.demo | boolean | yes | true — no AI model is configured, the rule-based parser only (demo mode). |
parsed.ai_skipped | "not_configured" | "disabled" | "not_needed" | "rate_limited" | "budget_exhausted" | "timeout" | "error" | "invalid" | "refusal" | null | yes | Why the model was not used (null when it was). |
parsed.ignored | string[] | yes | Words that could not be turned into a filter. |
parsed.unsupported_markets | string[] | yes | Markets outside the EU catalogue the query asked for (us, kr, cn ...): not searchable here. |
parsed.price_original | object | yes | Price as written in the query (before conversion to EUR at the ECB/NBU rate). |
parsed.catalog_url | string | null | yes | Public site catalogue page with these filters (null if not configured). |
items | object[] | yes | |
items[].id | string | no | |
items[].slug | string | no | |
items[].title | string | no | |
items[].make | string | no | |
items[].makeSlug | string | no | |
items[].model | string | no | |
items[].modelSlug | string | no | |
items[].trim | string | null | no | |
items[].year | integer | null | no | |
items[].firstRegistration | string | null | no | |
items[].mileageKm | integer | null | no | |
items[].powerKw | integer | null | no | |
items[].engineCc | integer | null | no | |
items[].batteryKwh | number | null | no | |
items[].fuel | "petrol" | "diesel" | "hybrid" | "phev" | "ev" | "lpg" | "cng" | "hydrogen" | "other" | null | no | |
items[].gearbox | "manual" | "automatic" | "cvt" | "robot" | "other" | null | no | |
items[].body | "sedan" | "hatchback" | "wagon" | "suv" | "crossover" | "coupe" | "convertible" | "minivan" | "van" | "pickup" | "truck" | "motorcycle" | "other" | null | no | |
items[].drive | "fwd" | "rwd" | "awd" | "4wd" | null | no | |
items[].color | string | null | no | |
items[].priceEur | integer | null | no | |
items[].netPriceEur | integer | null | no | |
items[].vat | "deductible" | "included" | "unknown" | no | |
items[].landedEur | integer | null | no | |
items[].dealScore | number | null | no | |
items[].country | "de" | "at" | "nl" | "be" | "lu" | "fr" | "dk" | "se" | "no" | "fi" | "ee" | "lv" | "lt" | "pl" | "cz" | "sk" | "it" | "es" | no | |
items[].city | string | null | no | |
items[].sellerType | "dealer" | "private" | "unknown" | no | |
items[].photos | string (uri)[] | no | |
items[].photoCount | integer | no | |
items[].publicationsCount | integer | no | |
items[].sourceKeys | string[] | no | |
items[].firstSeenAt | string | no | |
items[].lastSeenAt | string | no | |
items[].listedAt | string | no | |
items[].priceDrop | object | no | |
items[].cloneCount | integer | no | |
total | integer | yes | |
page | integer | yes | |
page_size | integer | yes | |
catalog_url | string | null | yes | Public site catalogue page with these filters. |
freshness | object[] | yes | |
freshness[].sourceKey | string | no | |
freshness[].lastCrawlAt | string | null | no | |
freshness[].health | string | no | |
took_ms | integer | yes |
400
Invalid request parameters or body (code validation_error).
application/problem+json · Schema: Problem
401
Missing, malformed, unknown, revoked or expired API key (code unauthorized).
application/problem+json · Schema: Problem
403
The API key lacks the scope required by this endpoint (code insufficient_scope).
application/problem+json · Schema: Problem
429
Rate limit exceeded for the tenant plan (code rate_limited). Wait Retry-After seconds.
application/problem+json · Schema: Problem
503
The catalogue (search index) is not configured or unavailable.
application/problem+json · Schema: Problem