# Pickles Auctions API (Australia) — search live pickles.com.au auction lots: salvage and insurance write-off cars, dealer-trade vehicles, trucks, earthmoving plant, trailers, caravans, boats and government/industrial general goods. Filter by make, model, year, odometer, state, write-off (WOVR) status, buy method and sale event, then pull the full lot record (VIN, rego, odometer, damage, equipment, every photo, auction end time) plus the live auction calendar. No login, no API key.

> Search live Pickles auction lots. Free-text `query` and/or structured filters (category, asset_type, make, model, badge, series, year or year_min/year_max, odometer_min/max, hours_max, state + city, buy_method, salvage, wovr, body, fuel_type, transmission, drive_type, colour, vendor, sale_id, price_min/max, has_keys). Sortable and paginated. PASS AT LEAST ONE of `query` or a filter — with neither, you get the whole live catalogue (10 959 lots on 2026-10-01). Every filter is AND-ed server-side against the live index, and `meta.total_results` is the exact upstream count so you can verify a filter bit.
> ReefAPI engine `pickles` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/pickles/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). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/pickles/v1/search — 3 credits
Search live Pickles auction lots. Free-text `query` and/or structured filters (category, asset_type, make, model, badge, series, year or year_min/year_max, odometer_min/max, hours_max, state + city, buy_method, salvage, wovr, body, fuel_type, transmission, drive_type, colour, vendor, sale_id, price_min/max, has_keys). Sortable and paginated. PASS AT LEAST ONE of `query` or a filter — with neither, you get the whole live catalogue (10 959 lots on 2026-10-01). Every filter is AND-ed server-side against the live index, and `meta.total_results` is the exact upstream count so you can verify a filter bit.

**Parameters:**
- `query` (string, optional) — Free-text keyword across the whole lot catalogue (make, model, badge, description, vendor, sale name). Leave it out to browse with filters only. Either `query` or at least one filter is strongly recommended — with neither you get the whole live catalogue, newest-relevance order.
- `category` (enum, optional) — Pickles top-level catalogue. Live lot counts per category come from the `facets` action (field=category). [one of: cars, trucks, motorcycles, caravans, boats, trailers, machinery, earthmoving-and-mobile-plant, general-goods, computers-smartphones-office-machines]
- `asset_type` (enum, optional) — Asset class as Pickles classifies the item itself (a narrower axis than `category`). [one of: vehicle, truck, motorcycle, caravan, trailer, marine, emp, machinery, generalgoods, itofficeequipment]
- `make` (string, optional) — Vehicle make, matched exactly and case-insensitively (toyota, ford, hyundai, ldv …). The live make list with lot counts is the `facets` action with field=make.
- `model` (string, optional) — Vehicle model, matched exactly (Hilux, Ranger, Corolla). Pair with `make` when a model name is shared between makes.
- `badge` (string, optional) — Trim/badge key in Pickles' own 'make|model|badge' form, e.g. 'ford|ranger|xlt'. Get the exact keys from facets field=badge.
- `series` (string, optional) — Series/chassis key in Pickles' own 'make|model|series' form, e.g. 'ford|ranger|px-mkiii'. Keys come from facets field=series.
- `year` (integer, optional) — Exact build/model year. For a span use year_min / year_max.
- `year_min` (integer, optional) — Earliest model year (inclusive). Ignored when `year` is set.
- `year_max` (integer, optional) — Latest model year (inclusive). Ignored when `year` is set.
- `odometer_min` (integer, optional) — Minimum odometer reading in km.
- `odometer_max` (integer, optional) — Maximum odometer reading in km. Lots whose odometer the source does not publish are excluded by this filter.
- `hours_max` (integer, optional) — Maximum engine hours — for plant, machinery and trucks.
- `state` (enum, optional) — Australian state/territory the lot sits in. [one of: nsw, vic, qld, wa, sa, nt, tas, act, nat]
- `city` (string, optional) — City/metro inside `state` (sydney, melbourne, brisbane, perth …). Requires `state` — Pickles keys this filter as '<state>|<city>'. Exact keys: facets field=city.
- `buy_method` (enum, optional) — How the lot is sold. [one of: pickles_online, pickles_live, buy_now, eoi, auction]
- `salvage` (enum, optional) — Salvage / insurance write-off stock vs ordinary used stock. [one of: salvage, non_salvage]
- `wovr` (string, optional) — Written-Off Vehicle Register status, exact string as Pickles publishes it: 'Repairable Write-Off', 'Statutory Write-Off', 'Inspection Passed Repairable Writeoff', 'WOVR N/A'.
- `body` (string, optional) — Body style key (wagon, hatchback, sedan, utility-dual-cab …). Live keys + counts: facets field=body.
- `fuel_type` (string, optional) — Fuel type, exact string as Pickles publishes it ('Diesel', 'Petrol - Unleaded ULP', 'Petrol - Premium ULP', 'Electric' …). Live values: facets field=fuel_type.
- `transmission` (string, optional) — Transmission, exact string ('Automatic', 'Manual', 'Sports Automatic', 'Constantly Variable Transmission' …).
- `drive_type` (string, optional) — Drive type, exact string ('Front Wheel Drive', '4X4 Dual Range', 'FWD : Front Wheel Drive' …). Live values: facets field=drive_type.
- `colour` (string, optional) — Exterior colour family as Pickles records it (Red, White, Blue …).
- `vendor` (string, optional) — Selling vendor, exact name (insurers, fleets, government departments). Live vendor list: facets field=vendor.
- `sale_id` (integer, optional) — Restrict to one auction/sale event by its Pickles sale id — the `sale_id` the `auctions` action returns.
- `price_min` (number, optional) — Minimum advertised price in AUD. Only Buy-Now / fixed-price lots carry a price; auction lots are 0 upstream, so any price_min above 0 also limits you to priced stock.
- `price_max` (number, optional) — Maximum advertised price in AUD (see price_min for the auction-lot caveat).
- `has_keys` (boolean, optional) — True = only lots Pickles records as having keys.
- `sort` (enum, optional, default "relevance") — Result ordering. [one of: relevance, ending_soonest, ending_latest, sale_soonest, year_desc, year_asc, odometer_asc, odometer_desc, price_desc, price_asc]
- `page` (integer, optional, default 1) — 1-based page number. page × size must stay under ~100 000.
- `size` (integer, optional, default 20) — Lots per page, 1-100 (default 20).

**Returns:** lots[]{stock_number, title, summary, category, category_label, asset_type, lines_of_business, url, make, model, series, badge, year, build_year, compliance_date, body, colour, colour_manufacturer, doors, seats, engine_litres, engine_capacity, engine_type, cylinders, fuel_type, fuel_economy, transmission, gears, drive_type, power_kw, horsepower, odometer, odometer_note, kilometres, engine_hours, vin, serial_number, hull_id, registration_plate, registration_state, registration_expiry, has_keys, spare_keys, sold_with_plates, plates_count, service_history, is_salvage, salvage_label, wovr_status, incident_types[], driveable, engine_starts, burnt, price_aud, buy_now_price_aud, minimum_bid_aud, buy_method, selling_method, buy_now_during_auction, bidding_ends_at, for_sale, vendor_name, sale{sale_id, sale_number, name, status, selling_methods[], starts_at, ends_at, event_location, branch}, location_suburb, location_city, location_state, location_timezone, image_count, thumbnail, ancap_rating, green_star_rating, redbook_code, redbook_description, vfacts_class, gvm, gvm_unit, gcm, tare, towing_braked} + meta{total_results, pagination}

**Example request body:**
```json
{
  "make": "toyota",
  "size": 20
}
```

### POST https://api.reefapi.com/pickles/v1/lot_detail — 1 credit
Full record for one lot by `stock_number` (the digits at the end of a pickles.com.au/used/details/... URL, and the `stock_number` of any search row). Adds everything search trims: the long auction description, EVERY photo URL in order, standard equipment, accessories, fitted extras, option pack, ROPS/FOPS and physical dimensions — on top of all search fields. A stock number that is not in the live public catalogue returns NOT_FOUND, never an empty success.

**Parameters:**
- `stock_number` (string, required) — Pickles stock number, e.g. 62424123.

**Returns:** lot{stock_number, title, summary, category, category_label, asset_type, lines_of_business, url, make, model, series, badge, year, build_year, compliance_date, body, colour, colour_manufacturer, doors, seats, engine_litres, engine_capacity, engine_type, cylinders, fuel_type, fuel_economy, transmission, gears, drive_type, power_kw, horsepower, odometer, odometer_note, kilometres, engine_hours, vin, serial_number, hull_id, registration_plate, registration_state, registration_expiry, has_keys, spare_keys, sold_with_plates, plates_count, service_history, is_salvage, salvage_label, wovr_status, incident_types[], driveable, engine_starts, burnt, price_aud, buy_now_price_aud, minimum_bid_aud, buy_method, selling_method, buy_now_during_auction, bidding_ends_at, for_sale, vendor_name, sale{sale_id, sale_number, name, status, selling_methods[], starts_at, ends_at, event_location, branch}, location_suburb, location_city, location_state, location_timezone, image_count, thumbnail, ancap_rating, green_star_rating, redbook_code, redbook_description, vfacts_class, gvm, gvm_unit, gcm, tare, towing_braked, description, images[]{image_id, sequence, url}, standard_equipment[], accessories[], fitted_with[], other_extras[], option_pack, rops, fops, length, width, height}}

**Example request body:**
```json
{
  "stock_number": "62424123"
}
```

### POST https://api.reefapi.com/pickles/v1/auctions — 2 credits
The live Pickles auction/sale calendar, built from the lots that are currently on offer: sale id, sale name, start and end time, status, event location, selling branch, selling methods, the states its lots sit in and the EXACT number of live lots in it. Use a returned `sale_id` as search's `sale_id` filter to list that sale's catalogue. Optional `state` / `category` scope the calendar. NOTE: the exact number of live sales is always reported as `meta.sales_total`; the engine names as many of them as one catalogue scan reaches and reports that as `meta.sales_named` — it never pretends the list is complete.

**Parameters:**
- `state` (enum, optional) — Australian state/territory the lot sits in. [one of: nsw, vic, qld, wa, sa, nt, tas, act, nat]
- `category` (enum, optional) — Pickles top-level catalogue. Live lot counts per category come from the `facets` action (field=category). [one of: cars, trucks, motorcycles, caravans, boats, trailers, machinery, earthmoving-and-mobile-plant, general-goods, computers-smartphones-office-machines]
- `limit` (integer, optional, default 25) — How many sale events to return, soonest first (1-100, default 25).

**Returns:** auctions[]{sale_id, sale_number, name, status, selling_methods[], starts_at, ends_at, event_location, branch, states[], categories[], lot_count} + meta{sales_total, sales_named}

**Example request body:**
```json
{
  "limit": 10
}
```

### POST https://api.reefapi.com/pickles/v1/facets — 1 credit
The live filter taxonomy: every distinct value of one field across the lots currently on offer, with its exact lot count. This is how you discover the valid values for search's free-string filters (make, model, body, fuel_type, transmission, drive_type, colour, vendor, wovr) instead of guessing them. One cheap call, no lot bodies transferred.

**Parameters:**
- `field` (enum, required) — Which field's live values to list. [one of: make, model, badge, series, category, asset_type, body, fuel_type, transmission, drive_type, colour, salvage, wovr, buy_method, selling_method, vendor, year, line_of_business, state, city, sale_id, bid_end]
- `query` (string, optional) — Optional case-insensitive substring to narrow the returned value list (client-side on the bucket labels, not a catalogue search).
- `limit` (integer, optional, default 50) — Maximum number of distinct values (1-500, default 50), biggest lot count first.

**Returns:** field, values[]{value, lot_count} + meta{total_results}

**Example request body:**
```json
{
  "field": "make",
  "limit": 30
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

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