# KREAM API scraper — KREAM (kream.co.kr), South Korea's sneaker and streetwear resale market: search products, read the live market (lowest ask, highest bid, last trade, premium over release price) overall and per size with fast-delivery prices apart, recent trades, price charts, categories. Prices in KRW. No account, no browser.

> Search KREAM by keyword. Each product comes with its immediate-buy price (lowest ask), its discount against the release price, English and Korean names, brand, style code, category, fast-delivery availability and wish / review / trade counts. Sort by popularity, price, premium, wishes, reviews or release date and filter by brand, category, gender, shoe or clothing size, price range, delivery type and below-release-price. KREAM DRAW entries are removed unless you ask for them.
> ReefAPI engine `kream` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/kream/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 /kream/v1/search — 2 credits
Search KREAM by keyword. Each product comes with its immediate-buy price (lowest ask), its discount against the release price, English and Korean names, brand, style code, category, fast-delivery availability and wish / review / trade counts. Sort by popularity, price, premium, wishes, reviews or release date and filter by brand, category, gender, shoe or clothing size, price range, delivery type and below-release-price. KREAM DRAW entries are removed unless you ask for them.

**Parameters:**
- `query` (string, required) — What to look for, as typed on kream.co.kr: a brand, a model, a style code ('DD1391-100') or Korean text ('나이키'). KREAM corrects misspellings on its own — read `query_used` and `corrected`.
- `page` (integer, optional, default 1) — Result page, 1-based. KREAM returns 50 products per page; `has_more` says whether another page exists. Measured on 'nike' (42,489 results): pages 1-500 all distinct, page 999 empty.
- `sort` (enum, optional) — Result order. `sort_applied` is KREAM's own confirmation of the order used. [one of: recommended, popular, popular_men, popular_women, premium_desc, premium_asc, lowest_ask, highest_bid, most_wished, most_reviewed, newest_release]
- `category_id` (array, optional) — Only these KREAM categories — ids from `categories` (1 = sneakers, 34 = all shoes). Several ids are OR-ed.
- `brand` (array, optional) — Only these brands, by KREAM's English brand name ('Nike', 'New Balance', 'Jordan'). Several brands are OR-ed.
- `gender` (enum, optional) — Only products for this gender. [one of: men, women, kids]
- `shoe_size` (array, optional) — Only products with this shoe size in stock, in millimetres as KREAM lists them ('250', '270'). Prices on the rows become that size's prices.
- `clothing_size` (array, optional) — Only products with this clothing size ('S', 'M', 'L', 'XL', or a waist size such as '30'). Prices on the rows become that size's prices.
- `price_min` (integer, optional) — Lowest price in KRW (inclusive). KREAM keeps a product when ANY of its sizes is priced in the range, so a row's `price` (the overall lowest ask) can fall outside it.
- `price_max` (integer, optional) — Highest price in KRW (inclusive). Same any-size rule as price_min.
- `delivery` (array, optional) — Only products available with this delivery: fast (KREAM warehouse stock), fast_95 (warehouse stock with a minor box/condition note), normal (seller ships through inspection), overseas, brand (sent by the brand), free_shipping, warehouse_storage.
- `hide_sold_out` (boolean, optional, default false) — true hides products with no immediate-buy offer.
- `below_release_price` (boolean, optional, default false) — true keeps only products currently priced below their release price (정가이하).
- `include_draws` (boolean, optional, default false) — KREAM DRAW entries appear among products with a 100 KRW entry fee as their price. false (default) drops them and counts them in `draws_dropped`; true keeps them flagged `listing_type: draw`.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-6, default 3).

**Returns:** results[]{product_id (string), url, name (English), name_ko, name_tag (bracketed tag KREAM puts before some names: a coupon or refurbished grade), brand{id,name}, style_code, style_codes[], category{id, path[]}, listing_type ('resale' | 'brand_store' | 'draw'), product_type, image, price (number, KRW: the immediate-buy price = lowest ask for resale; the fixed price for brand-store rows; null when nobody is selling), price_display, price_type ('lowest_ask' | 'brand_store_price' | 'draw_entry_fee'), currency=KRW, pre_coupon_price (brand-store rows showing a KREAM coupon: the price before it — `price` is after the coupon), coupon_applied, discount_percent (KREAM's percentage below the release price, or below the list price on brand-store rows), discount_basis ('release_price' | 'list_price'), fast_delivery, sold_out_temporarily, upcoming_release_date, wish_count_approx / wish_count_display, review_count_approx / review_count_display, trade_count_approx / trade_count_display (KREAM abbreviates these on cards: '23.4만' ≈ 234,000), badges[], rating / rating_scale (null)}, count, total_results, page, page_size (50), has_more, next_page, draws_dropped, sort_applied (KREAM's own echo), query_used (the query KREAM actually searched), corrected, correction_type, rows_matching_query_words, query

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

### POST /kream/v1/product/detail — 2 credits
The full KREAM product by `product_id` (or URL): English and Korean names, brand, style code, colorway, release price and date, every image, and the live market — lowest ask, highest bid, last trade and its change, total trades, premium over the release price, last trade per delivery channel — plus every size with its own lowest ask, highest bid and normal / fast / 95점 fast-delivery asks, the 5 most recent trades, the 5 best asks and bids, wish and review counts and delivery options. Brand-store listings return their fixed price, list price and discount instead.

**Parameters:**
- `product_id` (string, required) — KREAM product id (the number in kream.co.kr/products/12831, returned by every search row), or the product URL.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-6, default 3).

**Returns:** product{product_id, url, name, name_ko, name_tag, listing_type ('resale' | 'brand_store'), brand{id, name, name_ko, type, saved_count}, style_code, style_codes[], colorway, gender, category, shop_category{id, path[]}, release_price, release_price_display, release_date, listed_at (brand-store only), image, images[], price (lowest ask; brand-store price), price_display, price_type, currency=KRW, original_price (brand-store list price, else null), discount_percent (brand-store only), price_label, in_stock, is_tradable, is_active, allowed_transactions[], market{lowest_ask, lowest_ask_display, highest_bid, highest_bid_display, last_sale_price, last_sale_change, last_sale_change_percent, total_sales, price_premium (lowest ask minus release price), price_premium_percent, fast_delivery_available, last_sale_by_channel{normal_delivery, fast_delivery, fast_delivery_95, overseas_delivery, verified_fast, integrated_inventory}{price, change, change_percent}} (null on brand-store), brand_store_sale{price, price_display, list_price, discount_percent, status, status_display, stock_quantity, store_name, store_url} (null on resale), size_count, sizes[]{size, option_key, lowest_ask, highest_bid, lowest_ask_normal_delivery, lowest_ask_fast_delivery, lowest_ask_fast_delivery_95}, recent_sales[]{price, size, fast_delivery, traded_at} (5), top_asks[]{price, size, fast_delivery, quantity} (5), top_bids[] (5), wish_count, review_count, rating / rating_scale (null), delivery_options[]{method, label, fee, note, description, applies_to[]}, notice{title, description}}

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

### POST /kream/v1/product/price_history — 2 credits
KREAM's price chart for a product over 1 month, 3 months, 6 months, 1 year or all time — for all sizes or for one size — as dated points with the first, last, lowest and highest price in the period.

**Parameters:**
- `product_id` (string, required) — KREAM product id (the number in kream.co.kr/products/12831, returned by every search row), or the product URL.
- `size` (string, optional) — Optional: one size exactly as `product/detail` lists it in `sizes[].size` ('270', 'M', 'ONE SIZE'). Leave empty for the all-sizes chart.
- `period` (enum, optional, default "1y") — Chart span. Each span is KREAM's own series; spans are not merged. [one of: 1m, 3m, 6m, 1y, all]
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-6, default 3).

**Returns:** product_id, name, size (null = all sizes), option_key, period, points[]{date, price}, points_count, empty_days_dropped, first_date, last_date, first_price, last_price, min_price, max_price, currency=KRW, market{lowest_ask, highest_bid, last_sale_price} (for that size when a size is given)

**Example request body:**
```json
{
  "product_id": "12831",
  "period": "1m"
}
```

### POST /kream/v1/category — 2 credits
Every product in one KREAM category, paged, with the same rows, sorts and filters as search. Category ids come from `categories`.

**Parameters:**
- `category_id` (string, required) — A KREAM category id from `categories` (level-1 ids such as 34 = shoes, or level-2 ids such as 1 = sneakers).
- `page` (integer, optional, default 1) — Result page, 1-based. KREAM returns 50 products per page; `has_more` says whether another page exists. Measured on 'nike' (42,489 results): pages 1-500 all distinct, page 999 empty.
- `sort` (enum, optional) — Result order. `sort_applied` is KREAM's own confirmation of the order used. [one of: recommended, popular, popular_men, popular_women, premium_desc, premium_asc, lowest_ask, highest_bid, most_wished, most_reviewed, newest_release]
- `brand` (array, optional) — Only these brands, by KREAM's English brand name ('Nike', 'New Balance', 'Jordan'). Several brands are OR-ed.
- `gender` (enum, optional) — Only products for this gender. [one of: men, women, kids]
- `shoe_size` (array, optional) — Only products with this shoe size in stock, in millimetres as KREAM lists them ('250', '270'). Prices on the rows become that size's prices.
- `clothing_size` (array, optional) — Only products with this clothing size ('S', 'M', 'L', 'XL', or a waist size such as '30'). Prices on the rows become that size's prices.
- `price_min` (integer, optional) — Lowest price in KRW (inclusive). KREAM keeps a product when ANY of its sizes is priced in the range, so a row's `price` (the overall lowest ask) can fall outside it.
- `price_max` (integer, optional) — Highest price in KRW (inclusive). Same any-size rule as price_min.
- `delivery` (array, optional) — Only products available with this delivery: fast (KREAM warehouse stock), fast_95 (warehouse stock with a minor box/condition note), normal (seller ships through inspection), overseas, brand (sent by the brand), free_shipping, warehouse_storage.
- `hide_sold_out` (boolean, optional, default false) — true hides products with no immediate-buy offer.
- `below_release_price` (boolean, optional, default false) — true keeps only products currently priced below their release price (정가이하).
- `include_draws` (boolean, optional, default false) — KREAM DRAW entries appear among products with a 100 KRW entry fee as their price. false (default) drops them and counts them in `draws_dropped`; true keeps them flagged `listing_type: draw`.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-6, default 3).

**Returns:** results[]{product_id (string), url, name (English), name_ko, name_tag (bracketed tag KREAM puts before some names: a coupon or refurbished grade), brand{id,name}, style_code, style_codes[], category{id, path[]}, listing_type ('resale' | 'brand_store' | 'draw'), product_type, image, price (number, KRW: the immediate-buy price = lowest ask for resale; the fixed price for brand-store rows; null when nobody is selling), price_display, price_type ('lowest_ask' | 'brand_store_price' | 'draw_entry_fee'), currency=KRW, pre_coupon_price (brand-store rows showing a KREAM coupon: the price before it — `price` is after the coupon), coupon_applied, discount_percent (KREAM's percentage below the release price, or below the list price on brand-store rows), discount_basis ('release_price' | 'list_price'), fast_delivery, sold_out_temporarily, upcoming_release_date, wish_count_approx / wish_count_display, review_count_approx / review_count_display, trade_count_approx / trade_count_display (KREAM abbreviates these on cards: '23.4만' ≈ 234,000), badges[], rating / rating_scale (null)}, count, total_results, page, page_size (50), has_more, next_page, draws_dropped, sort_applied (KREAM's own echo), query_used (the query KREAM actually searched), corrected, correction_type, rows_matching_query_words, category_id

### POST /kream/v1/categories — 1 credit
KREAM's category tree: the top-level categories, or the sub-categories of one of them, with the `category_id` to pass to `category` or to search's category filter.

**Parameters:**
- `parent` (string, optional) — Optional: a level-1 `key` (or its `category_id`) from `categories` to list its sub-categories. Leave empty for the top level.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-6, default 3).

**Returns:** categories[]{name (Korean, as KREAM names it), key, category_id, level}, count, parent

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