# Wildberries API scraper — Russia's largest marketplace plus Kazakhstan, Belarus, Armenia, Kyrgyzstan, Uzbekistan, Tajikistan and Georgia: keyword search, category listings with sorts and filters, full product records with every size's price and stock, price history, reviews, seller records and search suggestions, priced in each country's currency. No account, no browser.

> Search Wildberries by keyword in one country: 100 products a page with price and struck price, stock, rating and review count, brand, seller and delivery time, priced for that country. Filter by brand, seller and price; page 1 can also return the site's filter list.
> ReefAPI engine `wildberries` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/wildberries/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 /wildberries/v1/search — 1 credit
Search Wildberries by keyword in one country: 100 products a page with price and struck price, stock, rating and review count, brand, seller and delivery time, priced for that country. Filter by brand, seller and price; page 1 can also return the site's filter list.

**Parameters:**
- `query` (string, required) — Search words, as typed on wildberries.ru (Russian or Latin).
- `country` (enum, optional, default "ru") — Wildberries market. Offers, stock and prices are those for delivery to the country's capital (Moscow, Almaty, Minsk, Yerevan, Bishkek, Tashkent, Dushanbe, Tbilisi), in its currency. Azerbaijan is not available. [one of: ru, kz, by, am, kg, uz, tj, ge]
- `page` (integer, optional, default 1) — Result page, 100 products per page. Wildberries serves 3 pages of a keyword search.
- `sort` (enum, optional, default "popular") — Wildberries' own sort orders. On broad keywords Wildberries applies a sort only together with a brand or seller filter; otherwise the answer lists it in ignored_params. [one of: popular, rating, price_asc, price_desc, newest, best_value]
- `price_min` (number, optional) — Lowest price, in the country's currency.
- `price_max` (number, optional) — Highest price, in the country's currency.
- `brand_ids` (array, optional) — Brand ids (up to 20), from `available_filters` or a result row's brand_id.
- `seller_ids` (array, optional) — Seller ids to keep (up to 20); -100 is Wildberries itself.
- `include_filters` (boolean, optional, default false) — Also return the site's filter list (brands, sellers, categories with ids) — one extra request.
- `include_fallback_results` (boolean, optional, default false) — When Wildberries answers a query it cannot match with unrelated products, return them separately in `fallback_results` instead of dropping them.
- `max_rotations` (integer, optional, default 10) — Advanced: how many attempts a request Wildberries rate-limits may take (1-12; category and seller listings use twice this number).

**Returns:** results[{position, product_id, root_id (the product family shared by colour variants), title, brand, brand_id, seller{id, name, rating}, url, image, image_count, price (cheapest size, what the buyer pays: goods price + WB logistics fee), was_price (struck price on the same footing, only when discounted), discount_percent (goods price vs struck goods price), price_max (dearest size, when sizes differ), currency, price_before_logistics, logistics_fee, available, stock_quantity, size_count, colours[], rating, rating_scale, review_count, category_id, parent_category_id, delivery_hours, is_new, review_reward_points, price_source (live: read from the product card; search_index: the product card did not answer, figures from the search index)}], count, page, page_size, total_results, total_pages, has_more, query, query_corrected_to, ranking_source (site|ru_index), unavailable_in_country_dropped, index_only_rows, sort_applied, ignored_params[], applied_filters{}, available_filters[{key, name, values[{id, name}]}] (include_filters), fallback_results_dropped, fallback_results[], sponsored_dropped, page_notice, country{code, name, currency, delivery_city, delivery_zone}

**Example request body:**
```json
{
  "query": "кроссовки"
}
```

### POST /wildberries/v1/category/products — 1 credit
List one Wildberries category in one country with the site's six sort orders and its price and brand filters: 100 products a page with the same fields as search.

**Parameters:**
- `category` (string, required) — Category id from `categories`, or a wildberries.ru category URL (https://www.wildberries.ru/catalog/…).
- `country` (enum, optional, default "ru") — Wildberries market. Offers, stock and prices are those for delivery to the country's capital (Moscow, Almaty, Minsk, Yerevan, Bishkek, Tashkent, Dushanbe, Tbilisi), in its currency. Azerbaijan is not available. [one of: ru, kz, by, am, kg, uz, tj, ge]
- `page` (integer, optional, default 1) — Result page, 100 products per page.
- `sort` (enum, optional, default "popular") — Wildberries' own sort orders. [one of: popular, rating, price_asc, price_desc, newest, best_value]
- `price_min` (number, optional) — Lowest price, in the country's currency.
- `price_max` (number, optional) — Highest price, in the country's currency.
- `brand_ids` (array, optional) — Brand ids (up to 20), from `available_filters` or a result row's brand_id.
- `seller_ids` (array, optional) — Seller ids to keep (up to 20); -100 is Wildberries itself.
- `max_rotations` (integer, optional, default 10) — Advanced: how many attempts a request Wildberries rate-limits may take (1-12; category and seller listings use twice this number).

**Returns:** results[{position, product_id, root_id (the product family shared by colour variants), title, brand, brand_id, seller{id, name, rating}, url, image, image_count, price (cheapest size, what the buyer pays: goods price + WB logistics fee), was_price (struck price on the same footing, only when discounted), discount_percent (goods price vs struck goods price), price_max (dearest size, when sizes differ), currency, price_before_logistics, logistics_fee, available, stock_quantity, size_count, colours[], rating, rating_scale, review_count, category_id, parent_category_id, delivery_hours, is_new, review_reward_points, price_source (live: read from the product card; search_index: the product card did not answer, figures from the search index)}], count, page, page_size, total_results, total_pages, has_more, category{category_id, name, path[], url}, sort_applied, applied_filters{}, page_notice, country{code, name, currency, delivery_city, delivery_zone}

### POST /wildberries/v1/categories — 1 credit
The Wildberries catalogue tree: every category with its id, name, path, parent and whether it can be listed with category/products.

**Parameters:**
- `parent_id` (integer, optional) — Only the direct children of this category id.
- `search` (string, optional) — Only categories whose name contains this text.
- `max_rotations` (integer, optional, default 10) — Advanced: how many attempts a request Wildberries rate-limits may take (1-12; category and seller listings use twice this number).

**Returns:** categories[{category_id, name, parent_id, depth, path[], url, has_products, child_count}], count

### POST /wildberries/v1/product/detail — 1 credit
One Wildberries product by article number or URL, for one country: title, brand, seller, every size with its own price, struck price and stock, colour variants with their prices, specifications, description, images, rating and review count, delivery time and the weekly price history.

**Parameters:**
- `product_id` (string, optional) — Wildberries article number (the number in a product URL; result rows return it).
- `url` (string, optional) — Alternative to product_id: a Wildberries product URL.
- `country` (enum, optional, default "ru") — Wildberries market. Offers, stock and prices are those for delivery to the country's capital (Moscow, Almaty, Minsk, Yerevan, Bishkek, Tashkent, Dushanbe, Tbilisi), in its currency. Azerbaijan is not available. [one of: ru, kz, by, am, kg, uz, tj, ge]
- `max_rotations` (integer, optional, default 10) — Advanced: how many attempts a request Wildberries rate-limits may take (1-12; category and seller listings use twice this number).

**Returns:** product{product_id, root_id, title, brand, brand_id, seller{id, name, rating}, url, images[], has_video, breadcrumb[], category_id, category, parent_category_id, parent_category, description, specifications[{group, name, value}], seller_sku, colour, contents, certificate_verified, gtin (null: not published), price, was_price, discount_percent, price_max, currency, price_before_logistics, logistics_fee, available, stock_quantity, delivery_hours, sizes[{size_id, name, original_name, price, was_price, discount_percent, price_before_logistics, logistics_fee, available, stock_quantity, warehouse_count, delivery_hours}], variants[{product_id, colour, price, was_price, available, stock_quantity, image}], rating, rating_scale, review_count, review_reward_points, price_history[{date, price}], price_history_currency (RUB), sold_in_country (false: no offer for this country, or sold out)}, country{code, name, currency, delivery_city, delivery_zone}

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

### POST /wildberries/v1/product/reviews — 1 credit
Reviews of one Wildberries product: the full star breakdown and counts, plus the most recent reviews (about 1 000, which is what Wildberries publishes) with stars, date, text, pros and cons, size fit, helpful votes, photos and the seller's answer. Reviewer names are never returned.

**Parameters:**
- `product_id` (string, optional) — Wildberries article number (the number in a product URL; result rows return it).
- `url` (string, optional) — Alternative to product_id: a Wildberries product URL.
- `page` (integer, optional, default 1) — Review page, 1-based.
- `limit` (integer, optional, default 50) — Reviews per page, 1-200.
- `rating` (array, optional) — Only reviews with these star ratings (1-5).
- `with` (enum, optional, default "all") — Keep only reviews with text or with photos. [one of: all, text, photos]
- `this_variant_only` (boolean, optional, default false) — Wildberries pools reviews across a product's colour variants; true keeps only the reviews written for this product_id.
- `max_rotations` (integer, optional, default 10) — Advanced: how many attempts a request Wildberries rate-limits may take (1-12; category and seller listings use twice this number).

**Returns:** product_id, root_id, rating, rating_scale, rating_breakdown{'1'..'5'}, review_count, reviews_with_text, reviews_with_photos, reviews_with_video, reviews_published, reviews_matching, reviews[{review_id, product_id, rating, date, text, pros, cons, variant_colour, variant_size, size_fit, helpful_count, unhelpful_count, tags[], photo_count, has_video, excluded_from_rating, reviewer_country, seller_answer{text, date}}], count, page, limit, total_pages, page_notice

### POST /wildberries/v1/seller/detail — 1 credit
A Wildberries seller's public record: shop name, legal name, trademark, tax id and registration number, and the registered address of companies.

**Parameters:**
- `seller_id` (string, required) — Wildberries seller id (result rows return it as seller.id).
- `max_rotations` (integer, optional, default 10) — Advanced: how many attempts a request Wildberries rate-limits may take (1-12; category and seller listings use twice this number).

**Returns:** seller{seller_id, name, legal_name, trademark, individual_entrepreneur, tax_id, registration_number, kpp, legal_address (companies only), url}

### POST /wildberries/v1/seller/products — 1 credit
One seller's products in one country with the site's sort orders and price and brand filters, 100 a page.

**Parameters:**
- `seller_id` (string, required) — Wildberries seller id (result rows return it as seller.id).
- `country` (enum, optional, default "ru") — Wildberries market. Offers, stock and prices are those for delivery to the country's capital (Moscow, Almaty, Minsk, Yerevan, Bishkek, Tashkent, Dushanbe, Tbilisi), in its currency. Azerbaijan is not available. [one of: ru, kz, by, am, kg, uz, tj, ge]
- `page` (integer, optional, default 1) — Result page, 100 products per page.
- `sort` (enum, optional, default "popular") — Wildberries' own sort orders. [one of: popular, rating, price_asc, price_desc, newest, best_value]
- `price_min` (number, optional) — Lowest price, in the country's currency.
- `price_max` (number, optional) — Highest price, in the country's currency.
- `brand_ids` (array, optional) — Brand ids (up to 20), from `available_filters` or a result row's brand_id.
- `max_rotations` (integer, optional, default 10) — Advanced: how many attempts a request Wildberries rate-limits may take (1-12; category and seller listings use twice this number).

**Returns:** results[{position, product_id, root_id (the product family shared by colour variants), title, brand, brand_id, seller{id, name, rating}, url, image, image_count, price (cheapest size, what the buyer pays: goods price + WB logistics fee), was_price (struck price on the same footing, only when discounted), discount_percent (goods price vs struck goods price), price_max (dearest size, when sizes differ), currency, price_before_logistics, logistics_fee, available, stock_quantity, size_count, colours[], rating, rating_scale, review_count, category_id, parent_category_id, delivery_hours, is_new, review_reward_points, price_source (live: read from the product card; search_index: the product card did not answer, figures from the search index)}], count, page, page_size, total_results, total_pages, has_more, seller_id, sort_applied, applied_filters{}, page_notice, country{code, name, currency, delivery_city, delivery_zone}

### POST /wildberries/v1/suggest — 1 credit
Wildberries search suggestions for the beginning of a query.

**Parameters:**
- `query` (string, required) — The beginning of a search, as typed.
- `max_rotations` (integer, optional, default 10) — Advanced: how many attempts a request Wildberries rate-limits may take (1-12; category and seller listings use twice this number).

**Returns:** query, suggestions[{text, type}], count

**Example request body:**
```json
{
  "query": "кроссовки"
}
```

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