# Bazaraki API — Cyprus's largest classifieds site (bazaraki.com): search cars, real estate for sale and rent, jobs, electronics and services by category, district, price and each category's own filters (make/model, year, mileage, fuel, gearbox; bedrooms, area, furnishing), and read one ad in full — EUR price, every listed attribute, photos, publish date, views and the seller (private or business, active ad count). No login, no key.

> Search live ads: by category path, text, district, seller, EUR price band and the category's own filters, sorted newest / cheapest / most expensive / by relevance, 30 rows a page.
> ReefAPI engine `bazaraki` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/bazaraki/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/bazaraki/v1/search — 2 credits
Search live ads: by category path, text, district, seller, EUR price band and the category's own filters, sorted newest / cheapest / most expensive / by relevance, 30 rows a page.

**Parameters:**
- `category` (string, optional) — A category `path` exactly as the categories action returns it, e.g. `real-estate-to-rent/apartments-flats`, `car-motorbikes-boats-and-parts/cars-trucks-and-vans/bmw` (brand) or `.../bmw/3-series` (model). A bazaraki.com category URL is accepted too. Omit it to search every category. An unknown path is rejected (the site itself would silently return the whole site).
- `query` (string, optional) — Free-text search over titles and descriptions. With a query the total is capped by the source at ~999 (measured: 997 BMW matches in Cars while the BMW category holds 1 520), so `total_is_exact` turns false at 990-999.
- `city` (enum, optional) — One of Cyprus's five districts (measured in Cars: Limassol 5 671 of 12 574). [one of: nicosia, limassol, larnaca, paphos, famagusta]
- `seller_id` (integer, optional) — Only this seller's ads — the `seller.id` of any row (measured: one dealer's 56 car ads out of 12 574).
- `price_min` (number, optional) — Lowest price in EUR (measured in Cars: 10 001-20 000 → 3 062 of 12 574).
- `price_max` (number, optional) — Highest price in EUR.
- `sort` (enum, optional) — Row order. Default: `newest`, or `relevance` when a query is given. The source always lists paid VIP rows first, then TOP, then regular, and sorts INSIDE each block — see `promotion_type`. [one of: newest, cheapest, expensive, relevance]
- `filters` (object, optional) — Category filters by the category's own vocabulary (the `filters` action lists them): {key: value}. A key is the filter slug with or without `attrs__` (`fuel-type`, `attrs__number-of-bedrooms`); ranges take `<slug>_min` / `<slug>_max` (`year_min`, `mileage_max`, `area_min`). A value is the published label (`Electric`, `2021`, `SUV`) or the source's code; multi-choice filters take a list (`{"body-type": ["SUV", "Hatchback"]}`). Needs `category`. Unknown keys/values are rejected.
- `page` (integer, optional, default 1) — Page number, 30 rows a page (the source's own size). Past the last page the source answers 0 rows; `has_more` says when to stop.

**Returns:** rows[]: id, slug, url, title, price (EUR), price_display, price_display_matches, price_description, city, area, published, category_id, features[], images[], promoted, promotion, seller{id,name,is_business,verified}; plus total, total_is_exact, page, has_more, category{}, applied{}

**Example request body:**
```json
{
  "category": "car-motorbikes-boats-and-parts/cars-trucks-and-vans",
  "city": "limassol",
  "sort": "cheapest"
}
```

### POST https://api.reefapi.com/bazaraki/v1/listing — 2 credits
One ad in full: title, description, EUR price (with the page's own ld+json offer price as a check), every attribute the ad lists, photos, publish date, views, location and the seller block.

**Parameters:**
- `id` (integer, required) — The ad's numeric id — the `id` of a search row, or the number in `bazaraki.com/adv/<id>_<slug>/`. A full ad URL is accepted too.
- `slug` (string, optional) — Optional: the row's `slug`. Saves one small lookup; resolved from the id when absent.

**Returns:** id, slug, url, title, description, price, currency, price_display, price_matches_ld_offer, price_kind, date_raised, date_modified, published, views, favorites, city, area, latitude, longitude, categories[], features[{name,value,values}], images[], vin, seller{id,name,account_name,is_business,is_company,verified,active_ads,posting_since,profile_url,website,contact_channels}

**Example request body:**
```json
{
  "id": 6789207
}
```

### POST https://api.reefapi.com/bazaraki/v1/categories — 1 credit
The category tree, one level at a time, with live ad counts: the top level, or the sub-categories of a given category path (brands under Cars, models under a brand, property types).

**Parameters:**
- `category` (string, optional) — A category `path`; omit it for the top level. Returns that category and its sub-categories with live ad counts (brands under Cars, models under a brand).

**Returns:** category{id,name,path,ancestors,total_ads}, rows[]: id, name, path, count

**Example request body:**
```json
{
  "category": "car-motorbikes-boats-and-parts/cars-trucks-and-vans"
}
```

### POST https://api.reefapi.com/bazaraki/v1/filters — 2 credits
The filters one category offers (the vocabulary `search.filters` accepts): key, type and every choice with its label.

**Parameters:**
- `category` (string, required) — A category `path` from the categories action.

**Returns:** category{}, rows[]: slug, name, type, keys[], multi, free_number, choices[{value,label}]

**Example request body:**
```json
{
  "category": "car-motorbikes-boats-and-parts/cars-trucks-and-vans"
}
```

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