# Mascus API — live used heavy-machinery marketplace data from the global Mascus network (Volvo CE / Ritchie Bros.): ~497,000 live listings of second-hand construction plant, trucks and trailers, agricultural and forestry machines, forklifts and groundcare equipment from dealers in 80 countries, across 39 country front-ends and one shared catalogue. Filter on what a pricing or sourcing desk works with — make, model, year, hour meter, odometer, engine output, gross weight, condition, seller country and region, price band, auction-only or rental-only — then pull one listing in full: the seller's own asking price in the seller's own currency, VAT rate, every technical property they typed with its parsed number and unit, the description, the auction event with its bidding deadline, the rental day/week/month rates, the coordinates, the gallery and the dealer's business address. Plus the live category tree with per-node counts, facet counts, the site's own autocomplete, popular makes per sector, and one dealer's profile and full stock. No login, no API key.

> Search or browse the whole marketplace. Combine a keyword with any of the typed filters the source supports natively — sector, category, sub-category, make, model, condition, advert type, year window, price band, hour-meter band, odometer band, engine output, gross weight, seller country and region, has-a-price, has-a-photo, has-a-video, listed-in-the-last-N-days — and sort by price, year, listing date, hours, odometer, make or country. Up to 200 rows a page. 🔴 Two things worth knowing before you build a loop: only the first 10,000 rows of any query are retrievable (past that the source silently re-serves page 1, so this endpoint refuses the call instead), and `price`/`currency` are the seller's own asking price — NOT the number the country front-end displays, which is a live conversion and differs by up to 326x between front-ends for the same machine.
> ReefAPI engine `mascus` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/mascus/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.
- **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). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/mascus/v1/search — 3 credits
Search or browse the whole marketplace. Combine a keyword with any of the typed filters the source supports natively — sector, category, sub-category, make, model, condition, advert type, year window, price band, hour-meter band, odometer band, engine output, gross weight, seller country and region, has-a-price, has-a-photo, has-a-video, listed-in-the-last-N-days — and sort by price, year, listing date, hours, odometer, make or country. Up to 200 rows a page. 🔴 Two things worth knowing before you build a loop: only the first 10,000 rows of any query are retrievable (past that the source silently re-serves page 1, so this endpoint refuses the call instead), and `price`/`currency` are the seller's own asking price — NOT the number the country front-end displays, which is a live conversion and differs by up to 326x between front-ends for the same machine.

**Parameters:**
- `market` (enum, optional, default "com") — Which country front-end to read. All 39 share ONE catalogue, so this does NOT pick a different inventory: it picks the language of the labels on `detail`, `categories` and `suggest`, and 🔴 the UNITS — the international front-end ('com') reports the odometer in MILES, the other 38 in kilometres. `mileage_km` is normalised on every market and `mileage_km_min/max` is always in kilometres, so you never have to care. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE rather than a half-filled answer. [one of: com, uk, ie, au, nz, za, de, at, lu, nl, be, it, pt, mx, pl, cz, sk, hu, ro, bg, hr, si, rs, me, gr, se, no, dk, fi, ee, lt, lv, ua, ua_ru, tr, jp, kr, tw, ar]
- `currency` (string, optional, default "EUR") — The currency to convert into, one of the 131 the source supports (EUR, USD, GBP, PLN, SEK, CZK, HUF, TRY, JPY, ZAR…). 🔴 Two measured consequences. (1) `price_min`/`price_max` are bands IN THIS CURRENCY: the same 10,000-50,000 band answers 19,366 rows in EUR and 18,583 in USD. (2) The conversion appears as `price_converted` + `price_converted_currency`, never as `price` — `price` and `currency` are always the seller's own asking price and do not move with this parameter.
- `query` (string, optional) — Free-text keyword, as typed into the marketplace's own search box: a machine type ('excavator', 'bagger'), a make, a model, or several words. Extra words NARROW here rather than widen — measured: 'excavator' 46,033 rows, 'caterpillar 320' 2,273 — and an unmatched word gives an honest empty answer. 🔴 FREE TEXT IS SCORED IN THE CHOSEN FRONT-END'S OWN LANGUAGE, so the same word is a different query per market: 'excavator' answered 46,041 rows on the international front-end and 46,118 on the German one, and the first 40 rows of the two had NOT ONE listing in common (a make-and-model query such as 'Kubota M5-111D' does match identically on both). A result set that must be reproducible across markets has to be pinned with the typed filters or a dealer, not with free text.
- `catalog` (enum, optional) — One of the marketplace's six sectors. Comma-separate for several. 🔴 The value is the sector CODE, which differs from the URL slug on three of the six ('cargo-transport' not 'transportation', 'materialhandling' not 'material-handling', 'groundscare' not 'groundcare') — a value guessed off a URL returns zero rows, so the codes are published and validated here. [one of: construction, cargo-transport, agriculture, materialhandling, forestry, groundscare]
- `category` (array, optional) — Category code inside a sector, as the `categories` action returns it ('excavators', 'tractors', 'trucks', 'forklifts'). Comma-separate for several. An unknown code is answered honestly with zero rows rather than ignored, but reading the code out of `categories` or `suggest` is the way to be sure.
- `subcategory` (array, optional) — The third taxonomy level ('crawlerexcavators', 'miniexcavators', 'wheelexcavators'), from the `categories` action with a `category_code` set. This is how you get from 40,068 excavators to the 20,806 crawler excavators.
- `brand` (array, optional) — Make, spelled the way the source's own facet spells it ('CAT' not 'Caterpillar', 'John Deere', 'Volvo', 'Mercedes-Benz'). Case does not matter, the spelling does — read it from `facets` or let `suggest` map what a user typed. Measured to bite: 46,035 rows for 'excavator' → 9,913 for CAT.
- `model` (array, optional) — Model name, as the source's own type-ahead spells it. Only works with `brand` — a bare model name is ambiguous across makes, so it is rejected rather than returning an answer that looks filtered. Measured: brand=CAT + model=320 → 1,553 rows.
- `country` (array, optional) — Seller country, 2-letter ISO code. Comma-separate for several. 80 countries have stock on a typical query; the `facets` action lists them with counts. Measured to bite: 46,035 → 3,494 for DE.
- `region` (array, optional) — Seller region or province, by the NAME the source prints ('Bayern', 'Tennessee', 'Västernorrlands län') — not a code; `facets` returns the names that have stock. Measured to bite: 'Bayern' → 132 rows.
- `condition` (enum, optional) — Condition class. Comma-separate for several. The source stores these as numeric property ids; this takes the words and sends the ids. Measured: 46,035 → 4,458 for 'new'. [one of: used, new, reconditioned, remanufactured, demo, vintage, damaged, dismantled, operates_with_deficiencies, rental_possibility]
- `ad_type` (enum, optional) — The structural kind of advert. 🔴 An unknown value is NOT an error on this source: it is dropped and you get the whole unfiltered catalogue with HTTP 200, so this endpoint validates it instead of forwarding it. Measured to bite: 46,035 → 5,116 auction lots, → 333 rental machines. [one of: usedad, auctionad, rentalad]
- `year_min` (integer, optional) — Earliest year of construction, inclusive. 🔴 The source's own name for this filter is not the obvious one and the obvious one is accepted with HTTP 200 and then ignored, so a naive year window returns the unfiltered catalogue looking filtered. Here it bites: 46,035 → 11,205 for 2015-2020.
- `year_max` (integer, optional) — Latest year of construction, inclusive. Note the source carries seller-entered years as far ahead as 2027, so an open-ended upper bound is not the same as 'up to this year'.
- `price_min` (number, optional) — Lowest price to include, 🔴 IN THE `currency` YOU ASKED FOR (default EUR), not in the seller's currency. Measured: the same 10,000-50,000 band answers 19,366 rows in EUR and 18,583 in USD. Any price bound also excludes the listings that publish no price at all and the source's own 0 and 1 placeholder prices.
- `price_max` (number, optional) — Highest price to include, 🔴 in the `currency` you asked for (default EUR), not in the seller's currency. Setting it also excludes every listing that publishes no price at all.
- `operating_hours_min` (integer, optional) — Lowest hour-meter reading to include, in hours — the field a used-plant buyer prices on. Verified front-end independent, unlike the odometer: the 0-2,000 h band answers the same 412 rows on the international and the German front-end.
- `operating_hours_max` (integer, optional) — Highest hour-meter reading to include, in hours. Measured to bite: 46,035 → 412 for 0-2,000 h on the transport sector.
- `mileage_km_min` (integer, optional) — Lowest odometer reading to include, 🔴 ALWAYS IN KILOMETRES. The source filters in the front-end's own unit — the same 0-100,000 band answers 9,811 rows on the international front-end (miles) and 7,051 on the German one — so the unit is fixed at kilometres here and converted before the request leaves. Separate from `operating_hours_*` on purpose: the source publishes only one of the two per machine and they are not comparable.
- `mileage_km_max` (integer, optional) — Highest odometer reading to include, 🔴 always in kilometres whatever `market` is set to — the source filters in the front-end's own unit and this endpoint converts before the request leaves.
- `engine_output_min` (integer, optional) — Lowest engine output to include, in the source's own unit for the sector (hp on agricultural machines, kW on construction plant — the `facets` action's `engineoutput` group states which). Measured to bite: 46,035 → 8,604 for 100-300.
- `engine_output_max` (integer, optional) — Highest engine output to include, in the same unit the minimum uses — the source's own unit for that sector, which the `facets` action's `engineoutput` group states.
- `weight_min` (integer, optional) — Lowest gross weight to include, in kilogrammes. The source publishes a gross weight on most construction plant and most trucks; a listing without one is excluded by the source when either bound is set.
- `weight_max` (integer, optional) — Highest gross weight to include, in kilogrammes. Measured to bite: 46,035 rows for 'excavator' narrow to 9,217 for 1,000-20,000 kg.
- `with_price` (boolean, optional, default false) — Only listings that publish a price. Most of this marketplace does not — auction lots carry none at all and many dealers list 'price on request' — so this is the most useful narrowing filter for a pricing job. Measured: 46,035 → 32,305.
- `with_image` (boolean, optional, default false) — Only listings with at least one photograph. Measured: 46,035 → 45,396, so this marketplace is almost entirely illustrated.
- `with_video` (boolean, optional, default false) — Only listings with a video. Measured: 46,035 → 3,892.
- `listed_within_days` (enum, optional) — Only listings put online within the last N days, using the source's own shortcut. Pair it with `sort=newest` to poll a narrow query for new stock. Measured: 46,035 → 2,690 for the last 7 days. [one of: 1, 3, 7, 14, 30]
- `dealer_id` (string, optional) — Restrict to one dealer's stock, by the 8-character id the source's own dealer links use (also on every row as `seller.dealer_id`). 🔴 The full GUID is accepted by the source and answers 125 rows from FOUR different companies because its middle segment is shared, so a full GUID passed here is shortened for you and the answer is checked to contain exactly one company before it is returned.
- `sort` (enum, optional, default "relevance") — Result order. Every value was checked to change the DATA, not merely be accepted; 🔴 a value outside this list is accepted with HTTP 200 and then ignored, so it is validated here. Read the notes on `price_asc` and `hours_asc` first: both change WHICH rows you get, not only their order. [one of: relevance, price_asc, price_desc, year_desc, year_asc, newest, oldest, hours_asc, hours_desc, mileage_asc, mileage_desc, brand_asc, brand_desc, model_asc, model_desc, country_asc, country_desc]
- `page` (integer, optional, default 1) — Page number, from 1. 🔴 `page x page_size` must stay at or below 10,000: past that the source answers HTTP 200 and serves PAGE 1'S ROWS under the page number you asked for (measured at four page sizes), so the combination is refused rather than letting a paging loop re-ingest the first page for ever. `meta.pagination` publishes `last_page`, `retrievable_max` and an honest `has_more`.
- `page_size` (integer, optional, default 40) — Rows per page, 1-200 (the source's own default is 40). A large page is the cheap way to the 10,000-row ceiling: at 200 it takes 50 calls instead of 250.
- `include_facets` (boolean, optional, default false) — Also return the source's own live filter counts for this exact query, in the same call. Same content as the `facets` action; set it here when you want rows and counts together.

**Returns:** listings[]: listing_id, asset_id (the id the `detail` action takes), url, listing_type (classified | auction | rental | marketplace_external), brand, model, year, catalog, category, operating_hours + operating_hours_unit, mileage + mileage_unit, mileage_km (ALWAYS kilometres, normalised — the international front-end reports miles) + mileage_km_exact (false only on that one front-end, where the back conversion is +/-1 km), price + currency (the SELLER'S OWN asking price and currency, verified invariant across 10 country front-ends), price_on_request, price_eur, price_converted + price_converted_currency (only when you asked for a currency the seller did not price in), rental{daily, weekly, monthly, currency, vat_rate}, auction{event_name, starts_at, ends_at, country, city, lot_url, auction_house_listing_id}, location_city, location_country_code, seller{dealer_id, name, country, url}, image, image_count, video_count, featured, highlighted, listed_last_24h, listed_at. meta carries total, pagination (page, page_size, last_page, retrievable_max, has_more), price_filter_currency, filters_applied (what actually went to the source), facets when asked for, and any warnings.

**Example request body:**
```json
{
  "query": "excavator",
  "market": "com",
  "currency": "EUR",
  "page": 1,
  "page_size": 40
}
```

### POST https://api.reefapi.com/mascus/v1/detail — 3 credits
One listing in full, by id or URL. Returns the machine (make, model, model group, year, category path, hour meter, odometer normalised to kilometres), the price block (the seller's own asking price and currency, the EUR equivalent, the VAT rate, whether a price is published at all, and the source's own printed price rows), every technical property the seller typed — each with the source's own label in your chosen language, a language-free field name, and a parsed number and unit where there is one — the accessories list, the seller's free-text description in each language they wrote it in, the auction event with its bidding deadline and the auction house's own lot id, the rental day/week/month rates with and without VAT and the regions it can be hired in, the machine's own town, region, postcode, country and map coordinates, the dealer's business address and years on the marketplace, the finance/insurance/transport services offered, the full-size gallery and any videos, and the category breadcrumb.

**Parameters:**
- `asset_id` (string, optional) — The listing id, as every search row returns it in `asset_id` and as the last segment of any listing URL (a full URL is accepted and the id taken out of it; the source ignores every other path segment, so the slug need not be right). 🔴 An id here is not always valid on every front-end: measured, the id the international front-end prints resolves on three front-ends while the id the German one prints for the SAME machine answers HTTP 404 on the other two. Prefer the row's `url`; an id that does not resolve on the `market` asked for is tried on the two widest front-ends and `meta` says which one answered.
- `url` (string, optional) — A listing URL instead of an id — whichever you happen to have. Either `asset_id` or `url` is required.
- `market` (enum, optional, default "com") — Which country front-end to read. All 39 share ONE catalogue, so this does NOT pick a different inventory: it picks the language of the labels on `detail`, `categories` and `suggest`, and 🔴 the UNITS — the international front-end ('com') reports the odometer in MILES, the other 38 in kilometres. `mileage_km` is normalised on every market and `mileage_km_min/max` is always in kilometres, so you never have to care. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE rather than a half-filled answer. [one of: com, uk, ie, au, nz, za, de, at, lu, nl, be, it, pt, mx, pl, cz, sk, hu, ro, bg, hr, si, rs, me, gr, se, no, dk, fi, ee, lt, lv, ua, ua_ru, tr, jp, kr, tw, ar]

**Returns:** listing{listing_id, asset_id, url, listing_type, status_active, machine{}, price{price, currency, price_on_request, price_eur, vat_rate, has_price, rows[]}, location{}, seller{}, basics[], specs[] (field, label, value, number, unit, items[]), descriptions[], description, auction{}, rental{}, images[], thumbnails[], videos[], breadcrumb[], listed_at, updated_at, services{}}. No contact name, phone number or e-mail address is returned on any action of this endpoint.

**Example request body:**
```json
{
  "asset_id": "gu7q6jaj",
  "market": "com"
}
```

### POST https://api.reefapi.com/mascus/v1/categories — 1 credit
The marketplace's own taxonomy with live per-node listing counts: six sectors (construction 252,476 · transport 96,956 · agriculture 83,644 · material handling 27,455 · forestry 25,707 · groundcare 10,840) and, under each, the categories and sub-categories with the exact codes every other action's `category` and `subcategory` filters take. Pass a `category_code` to get one sector's sub-tree. Every count is the source's own live figure. 🔴 The filter code and the source's URL slug differ on three of the six sectors, so this is the action to read codes from rather than lifting them out of a URL.

**Parameters:**
- `market` (enum, optional, default "com") — Which country front-end to read. All 39 share ONE catalogue, so this picks the LANGUAGE this action answers in, not a different inventory. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE. [one of: com, uk, ie, au, nz, za, de, at, lu, nl, be, it, pt, mx, pl, cz, sk, hu, ro, bg, hr, si, rs, me, gr, se, no, dk, fi, ee, lt, lv, ua, ua_ru, tr, jp, kr, tw, ar]
- `category_code` (string, optional) — Return this node's sub-tree instead of the whole taxonomy. Takes a sector code ('construction', 'agriculture') and narrows the answer to that sector's categories and sub-categories with their live counts.

**Returns:** categories[]: code (what the filters take), name_from_slug, url, count, parent_code, level, has_children — flattened depth-first so the tree can be walked. meta.listings_total is the top-level counts added up.

**Example request body:**
```json
{
  "market": "com"
}
```

### POST https://api.reefapi.com/mascus/v1/facets — 2 credits
The source's own live filter counts for a query: which makes, countries, regions, categories, conditions, advert types, accessories and emission levels have stock and how much of it. This is how you learn the exact spelling a filter wants (the source wants 'CAT', not 'Caterpillar', and region NAMES rather than codes) and how to split a query that is deeper than the 10,000-row retrievable ceiling. Every group says in `value_kind` whether its values are names, ISO codes or the source's own numeric property ids — the ids are what the filter takes, so they are published as they are rather than guessed at.

**Parameters:**
- `market` (enum, optional, default "com") — Which country front-end to read. All 39 share ONE catalogue, so this does NOT pick a different inventory: it picks the language of the labels on `detail`, `categories` and `suggest`, and 🔴 the UNITS — the international front-end ('com') reports the odometer in MILES, the other 38 in kilometres. `mileage_km` is normalised on every market and `mileage_km_min/max` is always in kilometres, so you never have to care. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE rather than a half-filled answer. [one of: com, uk, ie, au, nz, za, de, at, lu, nl, be, it, pt, mx, pl, cz, sk, hu, ro, bg, hr, si, rs, me, gr, se, no, dk, fi, ee, lt, lv, ua, ua_ru, tr, jp, kr, tw, ar]
- `currency` (string, optional, default "EUR") — The currency to convert into, one of the 131 the source supports (EUR, USD, GBP, PLN, SEK, CZK, HUF, TRY, JPY, ZAR…). 🔴 Two measured consequences. (1) `price_min`/`price_max` are bands IN THIS CURRENCY: the same 10,000-50,000 band answers 19,366 rows in EUR and 18,583 in USD. (2) The conversion appears as `price_converted` + `price_converted_currency`, never as `price` — `price` and `currency` are always the seller's own asking price and do not move with this parameter.
- `query` (string, optional) — Free-text keyword, as typed into the marketplace's own search box: a machine type ('excavator', 'bagger'), a make, a model, or several words. Extra words NARROW here rather than widen — measured: 'excavator' 46,033 rows, 'caterpillar 320' 2,273 — and an unmatched word gives an honest empty answer. 🔴 FREE TEXT IS SCORED IN THE CHOSEN FRONT-END'S OWN LANGUAGE, so the same word is a different query per market: 'excavator' answered 46,041 rows on the international front-end and 46,118 on the German one, and the first 40 rows of the two had NOT ONE listing in common (a make-and-model query such as 'Kubota M5-111D' does match identically on both). A result set that must be reproducible across markets has to be pinned with the typed filters or a dealer, not with free text.
- `catalog` (enum, optional) — One of the marketplace's six sectors. Comma-separate for several. 🔴 The value is the sector CODE, which differs from the URL slug on three of the six ('cargo-transport' not 'transportation', 'materialhandling' not 'material-handling', 'groundscare' not 'groundcare') — a value guessed off a URL returns zero rows, so the codes are published and validated here. [one of: construction, cargo-transport, agriculture, materialhandling, forestry, groundscare]
- `category` (array, optional) — Category code inside a sector, as the `categories` action returns it ('excavators', 'tractors', 'trucks', 'forklifts'). Comma-separate for several. An unknown code is answered honestly with zero rows rather than ignored, but reading the code out of `categories` or `suggest` is the way to be sure.
- `subcategory` (array, optional) — The third taxonomy level ('crawlerexcavators', 'miniexcavators', 'wheelexcavators'), from the `categories` action with a `category_code` set. This is how you get from 40,068 excavators to the 20,806 crawler excavators.
- `brand` (array, optional) — Make, spelled the way the source's own facet spells it ('CAT' not 'Caterpillar', 'John Deere', 'Volvo', 'Mercedes-Benz'). Case does not matter, the spelling does — read it from `facets` or let `suggest` map what a user typed. Measured to bite: 46,035 rows for 'excavator' → 9,913 for CAT.
- `model` (array, optional) — Model name, as the source's own type-ahead spells it. Only works with `brand` — a bare model name is ambiguous across makes, so it is rejected rather than returning an answer that looks filtered. Measured: brand=CAT + model=320 → 1,553 rows.
- `country` (array, optional) — Seller country, 2-letter ISO code. Comma-separate for several. 80 countries have stock on a typical query; the `facets` action lists them with counts. Measured to bite: 46,035 → 3,494 for DE.
- `region` (array, optional) — Seller region or province, by the NAME the source prints ('Bayern', 'Tennessee', 'Västernorrlands län') — not a code; `facets` returns the names that have stock. Measured to bite: 'Bayern' → 132 rows.
- `condition` (enum, optional) — Condition class. Comma-separate for several. The source stores these as numeric property ids; this takes the words and sends the ids. Measured: 46,035 → 4,458 for 'new'. [one of: used, new, reconditioned, remanufactured, demo, vintage, damaged, dismantled, operates_with_deficiencies, rental_possibility]
- `ad_type` (enum, optional) — The structural kind of advert. 🔴 An unknown value is NOT an error on this source: it is dropped and you get the whole unfiltered catalogue with HTTP 200, so this endpoint validates it instead of forwarding it. Measured to bite: 46,035 → 5,116 auction lots, → 333 rental machines. [one of: usedad, auctionad, rentalad]
- `year_min` (integer, optional) — Earliest year of construction, inclusive. 🔴 The source's own name for this filter is not the obvious one and the obvious one is accepted with HTTP 200 and then ignored, so a naive year window returns the unfiltered catalogue looking filtered. Here it bites: 46,035 → 11,205 for 2015-2020.
- `year_max` (integer, optional) — Latest year of construction, inclusive. Note the source carries seller-entered years as far ahead as 2027, so an open-ended upper bound is not the same as 'up to this year'.
- `price_min` (number, optional) — Lowest price to include, 🔴 IN THE `currency` YOU ASKED FOR (default EUR), not in the seller's currency. Measured: the same 10,000-50,000 band answers 19,366 rows in EUR and 18,583 in USD. Any price bound also excludes the listings that publish no price at all and the source's own 0 and 1 placeholder prices.
- `price_max` (number, optional) — Highest price to include, 🔴 in the `currency` you asked for (default EUR), not in the seller's currency. Setting it also excludes every listing that publishes no price at all.
- `operating_hours_min` (integer, optional) — Lowest hour-meter reading to include, in hours — the field a used-plant buyer prices on. Verified front-end independent, unlike the odometer: the 0-2,000 h band answers the same 412 rows on the international and the German front-end.
- `operating_hours_max` (integer, optional) — Highest hour-meter reading to include, in hours. Measured to bite: 46,035 → 412 for 0-2,000 h on the transport sector.
- `mileage_km_min` (integer, optional) — Lowest odometer reading to include, 🔴 ALWAYS IN KILOMETRES. The source filters in the front-end's own unit — the same 0-100,000 band answers 9,811 rows on the international front-end (miles) and 7,051 on the German one — so the unit is fixed at kilometres here and converted before the request leaves. Separate from `operating_hours_*` on purpose: the source publishes only one of the two per machine and they are not comparable.
- `mileage_km_max` (integer, optional) — Highest odometer reading to include, 🔴 always in kilometres whatever `market` is set to — the source filters in the front-end's own unit and this endpoint converts before the request leaves.
- `with_price` (boolean, optional, default false) — Only listings that publish a price. Most of this marketplace does not — auction lots carry none at all and many dealers list 'price on request' — so this is the most useful narrowing filter for a pricing job. Measured: 46,035 → 32,305.
- `dealer_id` (string, optional) — Restrict to one dealer's stock, by the 8-character id the source's own dealer links use (also on every row as `seller.dealer_id`). 🔴 The full GUID is accepted by the source and answers 125 rows from FOUR different companies because its middle segment is shared, so a full GUID passed here is shortened for you and the answer is checked to contain exactly one company before it is returned.

**Returns:** facets[]: name, value_kind (name | iso_country_code | code | condition_id | property_id | un_region_code), values[] each with value, count, optional from/to for a range band and optional children[] for a nested group. meta.total is the query's own row count.

**Example request body:**
```json
{
  "catalog": "construction",
  "category": "excavators",
  "market": "com"
}
```

### POST https://api.reefapi.com/mascus/v1/suggest — 1 credit
The marketplace's own type-ahead for whatever a user has typed, in one list where every entry is tagged with its kind: make, model, model group, category (with the code the `category`/`subcategory` filters take) and dealer (with the id the `seller` action takes). Use it to turn free text into values the filters will actually match, instead of guessing a spelling the source answers with zero rows.

**Parameters:**
- `query` (string, required) — What the user has typed so far, from 2 characters up. The answer mixes makes, models, model groups, categories and dealers, each tagged with its kind and carrying the value the matching filter wants — so a UI never has to guess a spelling the source would answer with zero rows.
- `market` (enum, optional, default "com") — Which country front-end to read. All 39 share ONE catalogue, so this picks the LANGUAGE this action answers in, not a different inventory. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE. [one of: com, uk, ie, au, nz, za, de, at, lu, nl, be, it, pt, mx, pl, cz, sk, hu, ro, bg, hr, si, rs, me, gr, se, no, dk, fi, ee, lt, lv, ua, ua_ru, tr, jp, kr, tw, ar]

**Returns:** suggestions[]: kind (brand | model | model_group | category | dealer | other), name, and, depending on the kind, url, category_code_hint, brand or dealer_id.

**Example request body:**
```json
{
  "query": "cat 3",
  "market": "com"
}
```

### POST https://api.reefapi.com/mascus/v1/brands — 1 credit
The makes the marketplace itself promotes per sector, with a live listing count each — the source's own shortlist of the biggest manufacturers in construction, transport, agriculture, material handling, forestry and groundcare. A cheap, single-call answer to 'what is actually traded here and in what volume'. For the COMPLETE make list of a specific query, including the long tail, use `facets` and read its `brand` group.

**Parameters:**
- `market` (enum, optional, default "com") — Which country front-end to read. All 39 share ONE catalogue, so this picks the LANGUAGE this action answers in, not a different inventory. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE. [one of: com, uk, ie, au, nz, za, de, at, lu, nl, be, it, pt, mx, pl, cz, sk, hu, ro, bg, hr, si, rs, me, gr, se, no, dk, fi, ee, lt, lv, ua, ua_ru, tr, jp, kr, tw, ar]

**Returns:** sectors[]: catalog, brands[] (name, count). meta.record_count is the number of make entries across all sectors.

**Example request body:**
```json
{
  "market": "com"
}
```

### POST https://api.reefapi.com/mascus/v1/seller — 2 credits
One dealer's public business profile by id: company name, postal address (street, postcode, town, region, country), visiting address where they publish one, website, logo, their own description of the business, the makes they list themselves under, their branch outlets, map coordinates, and how long they have traded on this marketplace with the date that count runs from. 🔴 The source also returns a named salesperson, a direct e-mail, a mobile and a switchboard number on this object; none of it is returned here on any action. Use `seller_listings` for this dealer's stock.

**Parameters:**
- `dealer_id` (string, required) — The dealer's 8-character id, as every search row returns it in `seller.dealer_id`, as `suggest` returns it for a dealer match, and as the source's own dealer links carry it. A full GUID is shortened for you.
- `market` (enum, optional, default "com") — Which country front-end to read. All 39 share ONE catalogue, so this picks the LANGUAGE this action answers in, not a different inventory. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE. [one of: com, uk, ie, au, nz, za, de, at, lu, nl, be, it, pt, mx, pl, cz, sk, hu, ro, bg, hr, si, rs, me, gr, se, no, dk, fi, ee, lt, lv, ua, ua_ru, tr, jp, kr, tw, ar]

**Returns:** seller{dealer_id, name, url, street, postcode, city, region, country_code, visiting_street, visiting_city, website, logo, about, brands[], outlets[], member_since, years_on_marketplace, latitude, longitude}.

**Example request body:**
```json
{
  "dealer_id": "427244D9",
  "market": "com"
}
```

### POST https://api.reefapi.com/mascus/v1/seller_listings — 3 credits
One dealer's full stock, as rows identical to `search`, with every `search` filter and sort available on top. 🔴 This is the action the source makes easiest to get wrong: handing its dealer filter the complete GUID answers HTTP 200 with 125 rows from FOUR different companies, because the GUID's middle segment is shared. This endpoint sends only the short id the source's own dealer links use, and then checks that what came back really belongs to one company before returning it — if it does not, you get an error rather than four dealers' machines labelled as one.

**Parameters:**
- `dealer_id` (string, required) — The dealer's 8-character id, as every search row returns it in `seller.dealer_id`, as `suggest` returns it for a dealer match, and as the source's own dealer links carry it. A full GUID is shortened for you.
- `market` (enum, optional, default "com") — Which country front-end to read. All 39 share ONE catalogue, so this does NOT pick a different inventory: it picks the language of the labels on `detail`, `categories` and `suggest`, and 🔴 the UNITS — the international front-end ('com') reports the odometer in MILES, the other 38 in kilometres. `mileage_km` is normalised on every market and `mileage_km_min/max` is always in kilometres, so you never have to care. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE rather than a half-filled answer. [one of: com, uk, ie, au, nz, za, de, at, lu, nl, be, it, pt, mx, pl, cz, sk, hu, ro, bg, hr, si, rs, me, gr, se, no, dk, fi, ee, lt, lv, ua, ua_ru, tr, jp, kr, tw, ar]
- `currency` (string, optional, default "EUR") — The currency to convert into, one of the 131 the source supports (EUR, USD, GBP, PLN, SEK, CZK, HUF, TRY, JPY, ZAR…). 🔴 Two measured consequences. (1) `price_min`/`price_max` are bands IN THIS CURRENCY: the same 10,000-50,000 band answers 19,366 rows in EUR and 18,583 in USD. (2) The conversion appears as `price_converted` + `price_converted_currency`, never as `price` — `price` and `currency` are always the seller's own asking price and do not move with this parameter.
- `query` (string, optional) — Free-text keyword, as typed into the marketplace's own search box: a machine type ('excavator', 'bagger'), a make, a model, or several words. Extra words NARROW here rather than widen — measured: 'excavator' 46,033 rows, 'caterpillar 320' 2,273 — and an unmatched word gives an honest empty answer. 🔴 FREE TEXT IS SCORED IN THE CHOSEN FRONT-END'S OWN LANGUAGE, so the same word is a different query per market: 'excavator' answered 46,041 rows on the international front-end and 46,118 on the German one, and the first 40 rows of the two had NOT ONE listing in common (a make-and-model query such as 'Kubota M5-111D' does match identically on both). A result set that must be reproducible across markets has to be pinned with the typed filters or a dealer, not with free text.
- `catalog` (enum, optional) — One of the marketplace's six sectors. Comma-separate for several. 🔴 The value is the sector CODE, which differs from the URL slug on three of the six ('cargo-transport' not 'transportation', 'materialhandling' not 'material-handling', 'groundscare' not 'groundcare') — a value guessed off a URL returns zero rows, so the codes are published and validated here. [one of: construction, cargo-transport, agriculture, materialhandling, forestry, groundscare]
- `category` (array, optional) — Category code inside a sector, as the `categories` action returns it ('excavators', 'tractors', 'trucks', 'forklifts'). Comma-separate for several. An unknown code is answered honestly with zero rows rather than ignored, but reading the code out of `categories` or `suggest` is the way to be sure.
- `subcategory` (array, optional) — The third taxonomy level ('crawlerexcavators', 'miniexcavators', 'wheelexcavators'), from the `categories` action with a `category_code` set. This is how you get from 40,068 excavators to the 20,806 crawler excavators.
- `brand` (array, optional) — Make, spelled the way the source's own facet spells it ('CAT' not 'Caterpillar', 'John Deere', 'Volvo', 'Mercedes-Benz'). Case does not matter, the spelling does — read it from `facets` or let `suggest` map what a user typed. Measured to bite: 46,035 rows for 'excavator' → 9,913 for CAT.
- `model` (array, optional) — Model name, as the source's own type-ahead spells it. Only works with `brand` — a bare model name is ambiguous across makes, so it is rejected rather than returning an answer that looks filtered. Measured: brand=CAT + model=320 → 1,553 rows.
- `country` (array, optional) — Seller country, 2-letter ISO code. Comma-separate for several. 80 countries have stock on a typical query; the `facets` action lists them with counts. Measured to bite: 46,035 → 3,494 for DE.
- `condition` (enum, optional) — Condition class. Comma-separate for several. The source stores these as numeric property ids; this takes the words and sends the ids. Measured: 46,035 → 4,458 for 'new'. [one of: used, new, reconditioned, remanufactured, demo, vintage, damaged, dismantled, operates_with_deficiencies, rental_possibility]
- `ad_type` (enum, optional) — The structural kind of advert. 🔴 An unknown value is NOT an error on this source: it is dropped and you get the whole unfiltered catalogue with HTTP 200, so this endpoint validates it instead of forwarding it. Measured to bite: 46,035 → 5,116 auction lots, → 333 rental machines. [one of: usedad, auctionad, rentalad]
- `year_min` (integer, optional) — Earliest year of construction, inclusive. 🔴 The source's own name for this filter is not the obvious one and the obvious one is accepted with HTTP 200 and then ignored, so a naive year window returns the unfiltered catalogue looking filtered. Here it bites: 46,035 → 11,205 for 2015-2020.
- `year_max` (integer, optional) — Latest year of construction, inclusive. Note the source carries seller-entered years as far ahead as 2027, so an open-ended upper bound is not the same as 'up to this year'.
- `price_min` (number, optional) — Lowest price to include, 🔴 IN THE `currency` YOU ASKED FOR (default EUR), not in the seller's currency. Measured: the same 10,000-50,000 band answers 19,366 rows in EUR and 18,583 in USD. Any price bound also excludes the listings that publish no price at all and the source's own 0 and 1 placeholder prices.
- `price_max` (number, optional) — Highest price to include, 🔴 in the `currency` you asked for (default EUR), not in the seller's currency. Setting it also excludes every listing that publishes no price at all.
- `operating_hours_min` (integer, optional) — Lowest hour-meter reading to include, in hours — the field a used-plant buyer prices on. Verified front-end independent, unlike the odometer: the 0-2,000 h band answers the same 412 rows on the international and the German front-end.
- `operating_hours_max` (integer, optional) — Highest hour-meter reading to include, in hours. Measured to bite: 46,035 → 412 for 0-2,000 h on the transport sector.
- `with_price` (boolean, optional, default false) — Only listings that publish a price. Most of this marketplace does not — auction lots carry none at all and many dealers list 'price on request' — so this is the most useful narrowing filter for a pricing job. Measured: 46,035 → 32,305.
- `sort` (enum, optional, default "relevance") — Result order. Every value was checked to change the DATA, not merely be accepted; 🔴 a value outside this list is accepted with HTTP 200 and then ignored, so it is validated here. Read the notes on `price_asc` and `hours_asc` first: both change WHICH rows you get, not only their order. [one of: relevance, price_asc, price_desc, year_desc, year_asc, newest, oldest, hours_asc, hours_desc, mileage_asc, mileage_desc, brand_asc, brand_desc, model_asc, model_desc, country_asc, country_desc]
- `page` (integer, optional, default 1) — Page number, from 1. 🔴 `page x page_size` must stay at or below 10,000: past that the source answers HTTP 200 and serves PAGE 1'S ROWS under the page number you asked for (measured at four page sizes), so the combination is refused rather than letting a paging loop re-ingest the first page for ever. `meta.pagination` publishes `last_page`, `retrievable_max` and an honest `has_more`.
- `page_size` (integer, optional, default 40) — Rows per page, 1-200 (the source's own default is 40). A large page is the cheap way to the 10,000-row ceiling: at 200 it takes 50 calls instead of 250.

**Returns:** listings[]: listing_id, asset_id (the id the `detail` action takes), url, listing_type (classified | auction | rental | marketplace_external), brand, model, year, catalog, category, operating_hours + operating_hours_unit, mileage + mileage_unit, mileage_km (ALWAYS kilometres, normalised — the international front-end reports miles) + mileage_km_exact (false only on that one front-end, where the back conversion is +/-1 km), price + currency (the SELLER'S OWN asking price and currency, verified invariant across 10 country front-ends), price_on_request, price_eur, price_converted + price_converted_currency (only when you asked for a currency the seller did not price in), rental{daily, weekly, monthly, currency, vat_rate}, auction{event_name, starts_at, ends_at, country, city, lot_url, auction_house_listing_id}, location_city, location_country_code, seller{dealer_id, name, country, url}, image, image_count, video_count, featured, highlighted, listed_last_24h, listed_at. meta carries total, pagination (page, page_size, last_page, retrievable_max, has_more), price_filter_currency, filters_applied (what actually went to the source), facets when asked for, and any warnings. meta.dealer_id echoes the id the rows were verified against.

**Example request body:**
```json
{
  "dealer_id": "427244D9",
  "market": "com",
  "page_size": 40
}
```

## 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=mascus
- Human docs page: https://reefapi.com/docs/mascus
- Overview page: https://reefapi.com/mascus-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt
