# Kufar.by API scraper — search Belarus' largest classifieds marketplace: keyword, category, region/city and price-band search over ~6 million live ads with four sorts and paging, full ad detail with photos and every category attribute, plus the live category tree and the region/city table. Prices come back in the currency the SELLER chose (BYN/USD/EUR/RUB) with Kufar's own conversions beside them, and a negotiable ad returns null rather than a fake zero. Russian and Belarusian text is returned exactly as the source spells it. No account, public logged-out data only, no seller phone.

> Search Kufar classifieds by keyword and/or category, region, city/district, price band, ad type and seller type, with four sorts and paging (up to 200 ads per page). Kufar serves at most 1,000 ads per search (e.g. 5 pages of 200) even when `total_results` is larger: `reachable_results` says how many one search can reach, and to collect more split the search by `region` (1-7) and, for Minsk (region 7), by `area` (the `regions` action lists the ids) — measured 2026-11-15, the 7 regions summed to exactly the unsplit total.
> ReefAPI engine `kufar` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/kufar/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/kufar/v1/search — 1 credit
Search Kufar classifieds by keyword and/or category, region, city/district, price band, ad type and seller type, with four sorts and paging (up to 200 ads per page). Kufar serves at most 1,000 ads per search (e.g. 5 pages of 200) even when `total_results` is larger: `reachable_results` says how many one search can reach, and to collect more split the search by `region` (1-7) and, for Minsk (region 7), by `area` (the `regions` action lists the ids) — measured 2026-11-15, the 7 regions summed to exactly the unsplit total.

**Parameters:**
- `query` (string, optional) — Free-text search, in the site's own language (Russian/Cyrillic matches best — Kufar's ads are written in Russian). Omit it to browse a category, a region or the whole catalogue.
- `category` (string, optional) — Kufar SUBCATEGORY id — 17010 Мобильные телефоны, 1010 Квартиры, 2010 Легковые автомобили... The `categories` action lists every id. Kufar's own filter does NOT match top-level group ids (1000, 2000, 17000...): it answers them with an empty result, so this engine rejects a group id and names its subcategories instead.
- `region` (enum, optional) — Kufar region id (7 = Минск). The `regions` action returns the names and every city/district id inside each region. [one of: 1, 2, 3, 4, 5, 6, 7]
- `area` (integer, optional) — City or district id INSIDE the chosen region — requires `region`. Ids come from the `regions` action (region 7 → 22 Центральный…).
- `price_min` (integer, optional) — Minimum price in whole BYN roubles — the number Kufar prints beside the ad. Kufar filters on its own BYN conversion, so an ad quoted in USD is matched on its BYN figure. Kufar needs both ends of the band, so an omitted bound is filled with 0 / 9999999 BYN and the band actually applied comes back in `filters.prc` (kopecks). A price band always excludes negotiable ads — they carry no number to compare.
- `price_max` (integer, optional) — Maximum price in whole BYN roubles — the number Kufar prints beside the ad. Kufar filters on its own BYN conversion, so an ad quoted in USD is matched on its BYN figure. Kufar needs both ends of the band, so an omitted bound is filled with 0 / 9999999 BYN and the band actually applied comes back in `filters.prc` (kopecks). A price band always excludes negotiable ads — they carry no number to compare.
- `listing_type` (enum, optional) — Kufar's own ad type, query key `typ`. In real estate the same key is the deal type: `let` = long-term rent, `sell` = for sale (e.g. category 1010 Квартиры). Omit for all. [one of: sell, buy, let]
- `company_only` (boolean, optional, default false) — Only ads posted by registered companies/shops (measured: 4 100 of 21 641 `iphone` ads).
- `sort` (enum, optional, default "newest") — Ordering. Kufar has no relevance sort; `newest` is what the site itself shows by default. [one of: newest, oldest, price_asc, price_desc]
- `size` (integer, optional, default 30) — Ads per page, 1–200. Kufar clamps anything larger to 200 rather than erroring. Kufar serves at most 1,000 ads per search whatever the size, so size 200 reaches them in 5 pages, size 30 in 34.
- `page` (integer, optional, default 1) — 1-based page number (translated into Kufar's own opaque cursor). Kufar serves at most 1,000 ads per search: a page starting past ad 1,000 (size 200 → page 6+, size 30 → page 35+) comes back empty with the real `total_results`, `has_more: false` and `no_results_reason: result_cap_reached`. To get more than 1,000, split the search by `region` and, for Minsk (region 7), by `area`.
- `language` (enum, optional, default "ru") — Language of Kufar's own labels (category/region names). Ad titles and bodies are returned exactly as the seller typed them. [one of: ru, by]

**Returns:** total_results (every match Kufar counts), reachable_results (how many of them Kufar will serve for this search: at most 1,000), page, page_size, returned, has_more (false on the last reachable page), no_results_reason (null; `result_cap_reached` on a page past the 1,000-ad cap, `past_last_page` past the end of a smaller result) and listings[] with listing_id, url, title, description_excerpt, price, price_currency (the currency the seller chose), price_kind (fixed|negotiable), price_byn, price_conversions{BYN,USD,EUR,RUB}, category_id/category_name, region_id/region_name, area_id/area_name, listing_type, posted_at, seller_type (company|private), seller_name, seller_account_id, phone_hidden, promoted, highlighted, image, images[], image_thumbnails[], image_count and attributes[] (every category field Kufar publishes, with its own label and value). `description_excerpt` is Kufar's own `body_short`, which the source fills only for its real-estate vertical (measured 50/50 real-estate rows, 0/50 phone rows) — elsewhere it is null and the full text comes from the `listing` action.

**Example request body:**
```json
{
  "query": "холодильник"
}
```

### POST https://api.reefapi.com/kufar/v1/listing — 1 credit
Full detail of one Kufar ad by id or URL: the complete description, price in the seller's own currency with Kufar's conversions, location, posting time, seller display name and account id, every photo, and all category attributes. Text is returned as the seller wrote it (a phone typed into the description stays). The phone behind Kufar's reveal button is not requested — only Kufar's own `phone_hidden` flag.

**Parameters:**
- `listing_id` (string, optional) — Kufar ad id — the number in the ad URL and in every search row's `listing_id`. Give this or `url`.
- `url` (string, optional) — Full ad URL, exactly as a search row returns it (real-estate and car ads live on re./auto. subdomains — both are accepted).

**Returns:** the same row shape as `search` plus `description` (the full body) instead of `description_excerpt`. A removed or non-existent ad returns NOT_FOUND.

**Example request body:**
```json
{
  "url": "https://www.kufar.by/item/1087257888"
}
```

### POST https://api.reefapi.com/kufar/v1/categories — 1 credit
Kufar's live category tree — the resolver `search` needs, because the `category` filter takes numeric ids. 22 top-level groups and 214 subcategories, each with its Russian and Belarusian name.

**Parameters:**
- `category` (string, optional) — Omit to get all 22 top-level groups with their subcategories; pass a group id to get just that group.
- `language` (enum, optional, default "ru") — Language of Kufar's own labels (category/region names). Ad titles and bodies are returned exactly as the seller typed them. [one of: ru, by]

**Returns:** categories[] with id, name, name_ru, name_by, subcategory_count and subcategories[] (id, name, name_ru, name_by, parent_id).

**Example request body:**
```json
{
  "category": "17000"
}
```

### POST https://api.reefapi.com/kufar/v1/regions — 1 credit
Kufar's live region and city/district table — the resolver the `region` and `area` search filters need. Seven regions, each with every city/district id Kufar offers.

**Parameters:** none

**Returns:** regions[] with id, name_ru, name_by, area_count and areas[] (id, name_ru, name_by).

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