# Webmotors API — Brazil's largest car and motorbike marketplace: used-car search with the filters dealers actually use, full listing records with BOTH Brazilian years (ano de fabricação and ano do modelo), the FIPE reference price next to the asking price, the seller, and every photo.

> Search live Webmotors stock (carros and motos) by make, model, version, model-year range, price range, mileage range, transmission, fuel, body type, colour, doors, equipment, seller type or location. Returns the full listing row for every hit plus webmotors' own total for the query.
> ReefAPI engine `webmotors` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/webmotors/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /webmotors/v1/search — 2 credits
Search live Webmotors stock (carros and motos) by make, model, version, model-year range, price range, mileage range, transmission, fuel, body type, colour, doors, equipment, seller type or location. Returns the full listing row for every hit plus webmotors' own total for the query.

**Parameters:**
- `vehicle_type` (enum, optional, default "car") — car = carros, bike = motos. Both live in the same index. [one of: car, bike]
- `make` (string, optional) — Manufacturer exactly as webmotors spells it (see `makes_models`). Case-insensitive.
- `model` (string, optional) — Model name as webmotors spells it.
- `trim` (string, optional) — Version (`versão`) name as webmotors spells it.
- `year_min` (integer, optional) — Lowest ANO DO MODELO (model year) to include.
- `year_max` (integer, optional) — Highest ANO DO MODELO (model year) to include.
- `price_min` (integer, optional) — Lowest asking price in BRL.
- `price_max` (integer, optional) — Highest asking price in BRL.
- `mileage_min` (integer, optional) — Lowest odometer reading in km.
- `mileage_max` (integer, optional) — Highest odometer reading in km.
- `transmission` (array, optional) — One or more gearbox types, webmotors' own labels. [one of: Automática, Manual, CVT, Semi-automática, Automatizada, Automatizada DCT, Automático sequencial, Variável]
- `fuel` (array, optional) — One or more fuel types, webmotors' own labels (flex = 'Gasolina e álcool'). [one of: Gasolina e álcool, Gasolina, Diesel, Gasolina e elétrico, Álcool, Elétrico, Diesel e elétrico, Gasolina, álcool e gás natural, Gasolina e gás natural, Álcool e elétrico, Gás natural]
- `body_type` (array, optional) — One or more body styles. [one of: Utilitário esportivo, Hatchback, Sedã, Picape, Minivan, Perua/SW, Cupê, Conversível, Utilitário, Van/Utilitário]
- `exterior_color` (array, optional) — One or more exterior colours, webmotors' own labels.
- `doors` (array, optional) — Door counts to include (2, 3, 4).
- `seller_type` (array, optional) — dealer = Loja, dealership = Concessionária, private = Pessoa Física. [one of: dealer, dealership, private]
- `condition` (enum, optional) — new = 0 km, used = seminovos/usados. Omit for both. [one of: new, used]
- `armored` (boolean, optional) — true = only armoured (blindado), false = only non-armoured.
- `optionals` (array, optional) — Equipment the car must have, webmotors' own labels.
- `attributes` (array, optional) — Listing attributes: 'Aceita troca', 'IPVA pago', 'Licenciado', 'Único dono', 'Garantia de fábrica'.
- `final_plate` (array, optional) — Licence-plate last-digit groups, used for São Paulo's rodízio rule.
- `lifestyle` (string, optional) — Webmotors' own use-case buckets ('Carros para família', 'SUVs', 'Carros para aplicativos', 'Carros econômicos').
- `location` (string, optional) — Webmotors' own state/city slug ('sp', 'sp-sao-paulo', 'pr-curitiba').
- `engine_cc_min` (integer, optional) — Motorbikes only: smallest engine displacement in cc.
- `engine_cc_max` (integer, optional) — Motorbikes only: largest engine displacement in cc.
- `dealer_id` (integer, optional) — Return only this dealer's stock (`seller.seller_id` from any row).
- `sort` (enum, optional, default "relevance") — Result order. These five are the only orders webmotors publishes. Note that price_desc opens on unvalidated seller typos in the hundreds of millions of BRL — pair it with price_max. [one of: relevance, price_asc, price_desc, year_desc, mileage_asc]
- `page` (integer, optional, default 1) — 1-based page. `page_total` in the response is the source's own ceiling: it stops serving rows past ~10 000 per query however large `total_results` is, so narrow the filters to reach the rest.
- `page_size` (integer, optional, default 24) — Rows per page.

**Returns:** listings[]{listing_id, url, title, make, model, trim, year_manufacture, year_model, mileage_km, price, currency, fipe_percent, transmission, body_type, doors, exterior_color, engine_litres, power_hp, traction, armored, has_auction_record, condition, condition_new, attributes, description, images, image_count, seller{seller_id,name,type,type_label,is_dealer,city,state,state_code,neighborhood,street,zip,score}} + total_results, page, page_size, has_more

**Example request body:**
```json
{
  "make": "TOYOTA",
  "page_size": 24
}
```

### POST /webmotors/v1/listing — 2 credits
The complete record for one listing, from the URL `search` returns: every specification, all equipment, the full description, every photo, the seller with their CNPJ, address and opening hours, and — unlike the search row — the fuel type and the FIPE reference price alongside the asking price.

**Parameters:**
- `url` (string, required) — The listing URL, exactly as `search` returns it in `url`. A bare id cannot be resolved: webmotors validates the whole slug against the id.
- `include_reference_price` (boolean, optional, default true) — Also fetch the FIPE reference price and webmotors' market band (one extra upstream call, ~330 bytes).
- `include_phones` (boolean, optional, default true) — Also fetch the seller's published phone numbers — the same ones the site's 'ver telefone' control reveals without a login (one extra upstream call, ~110 bytes).

**Returns:** listing{listing_id, url, title, make, model, trim, year_manufacture, year_model, mileage_km, price, currency, fipe_percent, transmission, body_type, doors, exterior_color, engine_litres, power_hp, traction, armored, has_auction_record, condition, condition_new, attributes, description, images, image_count, seller{seller_id,name,type,type_label,is_dealer,city,state,state_code,neighborhood,street,zip,score}, fuel, optionals, lifestyle, promotions, fipe_code, fipe_price, created_at, seller{cnpj,member_since,opening_hours,phones}, reference_price{...}}

### POST /webmotors/v1/reference_price — 1 credit
The FIPE reference price for one listing (the Brazilian used-car price index) plus Webmotors' own lowest / average / highest asking price for the same vehicle in that state, each with its own update date. Takes the bare listing id.

**Parameters:**
- `listing_id` (integer, required) — Listing id (`listing_id` from `search`). This surface takes the bare id.
- `vehicle_type` (enum, optional, default "car") — car = carros, bike = motos. [one of: car, bike]

**Returns:** reference_price{make, model, trim, year, fipe_code, fipe_price, fipe_updated_at, market_state, market_lowest_price, market_average_price, market_highest_price, market_updated_at, currency}

### POST /webmotors/v1/makes_models — 1 credit
Webmotors' own make → model tree for cars or motorbikes — the exact spellings the `make` and `model` search filters expect.

**Parameters:**
- `vehicle_type` (enum, optional, default "car") — car = carros, bike = motos. [one of: car, bike]
- `make` (string, optional) — Return only this manufacturer's models instead of the whole tree.

**Returns:** makes[]{make, models[]}, make_count, model_count

## More
- Try it live, no code: https://reefapi.com/playground?engine=webmotors
- Human docs page: https://reefapi.com/docs/webmotors
- Overview page: https://reefapi.com/webmotors-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt