# Kaspi.kz API scraper — Kazakhstan's #1 marketplace: search by keyword or category with Kaspi's sort orders and filters, and read every product with specifications, variants, rating breakdown, every merchant's price and delivery promise per city, reviews and seller profiles. No account, no browser.

> Search Kaspi Магазин by keyword or browse a category, with Kaspi's five sort orders and its own filters (brand, price band, category-specific attributes). 12 products a page: product id, title, brand, URL, images, price in KZT, Kaspi bonus amount, instalment plan, rating and review count, category path, delivery speed. Page 1 also returns the total, the filter list with counts and the category tree.
> ReefAPI engine `kaspi` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/kaspi/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 /kaspi/v1/search — 2 credits
Search Kaspi Магазин by keyword or browse a category, with Kaspi's five sort orders and its own filters (brand, price band, category-specific attributes). 12 products a page: product id, title, brand, URL, images, price in KZT, Kaspi bonus amount, instalment plan, rating and review count, category path, delivery speed. Page 1 also returns the total, the filter list with counts and the category tree.

**Parameters:**
- `query` (string, optional) — Keyword, as typed on kaspi.kz (Russian, Kazakh or Latin). Optional when `category` is given.
- `category` (string, optional) — A Kaspi category id (Smartphones, Refrigerators, Headphones — the `category` values search returns in `categories`) or a category URL (https://kaspi.kz/shop/c/smartphones/).
- `filters` (array, optional) — Filter value ids exactly as returned in available_filters[].values[].id, e.g. ':manufacturerName:Samsung', ':price:100 000 - 149 999 т'. Ids the site does not apply come back in `ignored_filters`.
- `sort` (enum, optional, default "relevance") — Kaspi's own five search orders. [one of: relevance, price_asc, price_desc, rating, newest]
- `page` (integer, optional, default 1) — Result page, 1-based, 12 products per page (Kaspi's page size).
- `city` (string, optional, default "almaty") — Buyer city: a Kaspi city code (almaty, nur-sultan = Astana, shymkent, karaganda, aktobe, taraz, pavlodar, ust-kamenogorsk, semey, atyrau, kostanai, kyzylorda, uralsk, petropavlovsk, aktau, turkestan, taldykorgan …, 320 in total) or its numeric id (750000000). Delivery promises, the set of merchants that deliver and search availability follow the city. Unknown → INVALID_PARAM.
- `max_rotations` (integer, optional, default 3) — Advanced: how many exits to try for a difficult request (1-6, default 3).

**Returns:** results[{position, product_id, group_id (variant group id ending in 'b', else null), title, brand, url, image, images[], price (the listing's lowest-offer price; product/detail price_min is live), currency, bonus_amount (Kaspi bonus cashback, not a discount), price_after_bonus, installment{months, monthly_payment}, credit_available, rating, rating_scale, review_count, category_id, category_path[], delivery_duration, has_variants, brand_official_partner, top_merchant_id, stickers[], sold_by_unit, unit_label, listed_at}], count, page, page_size, total_results (page 1), total_pages (page 1), available_filters (page 1)[{key, title, type, values[{id, label, count, active}]}], applied_filters[], ignored_filters[], categories (page 1)[{category, title, count, active, depth}], category, category_title, completions[], sponsored_dropped, page_notice, city{id, code, name, name_ru}

**Example request body:**
```json
{
  "query": "iphone"
}
```

### POST /kaspi/v1/product/detail — 2 credits
One Kaspi product by id or URL: title, brand, images, category path, full specifications, description, variants (colour / size with their product ids), exact rating with 1-5 breakdown and counts, the cheapest price across merchants and the first page of merchant offers with price, pre-discount price, seller rating and delivery dates for the chosen city.

**Parameters:**
- `product_id` (string, optional) — Kaspi product id (the number at the end of a product URL; search rows return it as product_id).
- `url` (string, optional) — Alternative to product_id: a kaspi.kz product URL.
- `city` (string, optional, default "almaty") — Buyer city: a Kaspi city code (almaty, nur-sultan = Astana, shymkent, karaganda, aktobe, taraz, pavlodar, ust-kamenogorsk, semey, atyrau, kostanai, kyzylorda, uralsk, petropavlovsk, aktau, turkestan, taldykorgan …, 320 in total) or its numeric id (750000000). Delivery promises, the set of merchants that deliver and search availability follow the city. Unknown → INVALID_PARAM.
- `offers_limit` (integer, optional, default 10) — How many merchant offers (cheapest first) to include, 1-50.
- `max_rotations` (integer, optional, default 3) — Advanced: how many exits to try for a difficult request (1-6, default 3).

**Returns:** product{product_id, title, name, brand, url, images[], category_path[], category_ids[], master_category, description, description_ai_generated, specifications[{group, name, code, value, unit}], refund_period_days, max_quantity_per_order, age_restricted, listed_at, size_table_code, group_id, variants[{product_id, attributes[{name, value, size_system}], selected, image}], rating, rating_scale, rating_count, review_count, review_photo_count, rating_breakdown{'5'..'1'}, price_min (cheapest live offer), price_max (only when every offer was read), currency, offers_total, offers_returned, offers[{position, seller{id, name, rating, rating_scale, review_count}, price, was_price (only when the merchant shows a higher pre-discount price), discount_percent, currency, seller_sku, title, delivery_duration (EXPRESS|TODAY|TOMORROW|TILL_2_DAYS|TILL_5_DAYS|TILL_7_DAYS|OTHER), delivery_type, earliest_delivery_at, pickup_at, postomat_at, kaspi_delivery, preorder_days, delivery_options[{type, delivery_at, days, cost, free_from_order_total, kaspi_delivery, intercity}]}], delivery_duration_counts{}, available (any offer in this city)}, city{id, code, name, name_ru}

**Example request body:**
```json
{
  "product_id": "113137790"
}
```

### POST /kaspi/v1/product/offers — 1 credit
Every merchant offer for one Kaspi product in a city, paged: seller with rating and review count, price, pre-discount price, delivery speed and dates for courier, pickup and postomat, delivery cost and free-delivery threshold, preorder days.

**Parameters:**
- `product_id` (string, optional) — Kaspi product id (the number at the end of a product URL; search rows return it as product_id).
- `url` (string, optional) — Alternative to product_id: a kaspi.kz product URL.
- `city` (string, optional, default "almaty") — Buyer city: a Kaspi city code (almaty, nur-sultan = Astana, shymkent, karaganda, aktobe, taraz, pavlodar, ust-kamenogorsk, semey, atyrau, kostanai, kyzylorda, uralsk, petropavlovsk, aktau, turkestan, taldykorgan …, 320 in total) or its numeric id (750000000). Delivery promises, the set of merchants that deliver and search availability follow the city. Unknown → INVALID_PARAM.
- `sort` (enum, optional, default "price") — Kaspi's own three offer orders. [one of: price, rating, popular]
- `page` (integer, optional, default 1) — Offer page, 1-based.
- `limit` (integer, optional, default 20) — Offers per page, 1-50.
- `max_rotations` (integer, optional, default 3) — Advanced: how many exits to try for a difficult request (1-6, default 3).

**Returns:** product_id, offers[{position, seller{id, name, rating, rating_scale, review_count}, price, was_price (only when the merchant shows a higher pre-discount price), discount_percent, currency, seller_sku, title, delivery_duration (EXPRESS|TODAY|TOMORROW|TILL_2_DAYS|TILL_5_DAYS|TILL_7_DAYS|OTHER), delivery_type, earliest_delivery_at, pickup_at, postomat_at, kaspi_delivery, preorder_days, delivery_options[{type, delivery_at, days, cost, free_from_order_total, kaspi_delivery, intercity}]}], offers_returned, offers_total, total_pages, page, limit, sort, delivery_duration_counts{}, city{id, code, name, name_ru}

### POST /kaspi/v1/product/reviews — 1 credit
Reviews of one Kaspi product, paged: stars, date, text, pros and cons, helpful count, photos and the merchant it was bought from, plus the exact average, the 1-5 breakdown and the size of each review group. Reviewer names and order numbers are never returned.

**Parameters:**
- `product_id` (string, optional) — Kaspi product id (the number at the end of a product URL; search rows return it as product_id).
- `url` (string, optional) — Alternative to product_id: a kaspi.kz product URL.
- `sort` (enum, optional, default "popular") — Review order. [one of: popular, newest]
- `filter` (enum, optional, default "with_text") — Which reviews to list; `counts` returns the size of every group. [one of: with_text, all, with_photos, positive, negative]
- `page` (integer, optional, default 1) — Review page, 1-based.
- `limit` (integer, optional, default 20) — Reviews per page, 1-100.
- `max_rotations` (integer, optional, default 3) — Advanced: how many exits to try for a difficult request (1-6, default 3).

**Returns:** product_id, reviews[{review_id, rating, date, text, pros, cons, helpful_count, images[], seller{code, name}, edited}], reviews_returned, reviews_total (for the chosen filter), total_pages, page, limit, sort, filter, rating, rating_scale, rating_breakdown{'5'..'1'}, counts{all, with_text, with_photos, positive, negative}

### POST /kaspi/v1/seller/detail — 1 credit
A Kaspi merchant's public profile: name, logo, rating and review count, Kaspi status, the share of cancelled, returned and late orders, order-volume bracket and legal address.

**Parameters:**
- `seller_id` (string, required) — Kaspi merchant id, as returned in offers[].seller.id.
- `city` (string, optional, default "almaty") — Buyer city: a Kaspi city code (almaty, nur-sultan = Astana, shymkent, karaganda, aktobe, taraz, pavlodar, ust-kamenogorsk, semey, atyrau, kostanai, kyzylorda, uralsk, petropavlovsk, aktau, turkestan, taldykorgan …, 320 in total) or its numeric id (750000000). Delivery promises, the set of merchants that deliver and search availability follow the city. Unknown → INVALID_PARAM.
- `max_rotations` (integer, optional, default 3) — Advanced: how many exits to try for a difficult request (1-6, default 3).

**Returns:** seller{seller_id, name, logo, active, rating, rating_scale, review_count, status, new_seller, cancelled_orders_percent, returned_orders_percent, late_delivery_percent, orders_total_bracket, legal_address}

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