# KaBuM! API — Brazil's biggest PC hardware and electronics retailer as JSON: product search with filters that bite, category browsing, full product detail with the PIX/cash price and every instalment plan, stock, ratings, marketplace seller and specs, plus a 20-product batch price lookup from kabum.com.br — no API key, no login

> Search KaBuM! by keyword. Every row carries BOTH Brazilian prices — `price_brl` (the instalment/card reference) and `cash_price_brl` (the à-vista PIX/boleto price) — plus stock, the instalment plan, whether KaBuM or a marketplace seller ships it, and the `product_id` every other action takes. `facets` in the response lists the brands and category facets this query accepts, so the next call can filter without guessing.
> ReefAPI engine `kabum` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/kabum/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/kabum/v1/search — 2 credits
Search KaBuM! by keyword. Every row carries BOTH Brazilian prices — `price_brl` (the instalment/card reference) and `cash_price_brl` (the à-vista PIX/boleto price) — plus stock, the instalment plan, whether KaBuM or a marketplace seller ships it, and the `product_id` every other action takes. `facets` in the response lists the brands and category facets this query accepts, so the next call can filter without guessing.

**Parameters:**
- `query` (string, required) — What a Brazilian shopper would type: a product name, a model ('rtx 5070', 'ryzen 7 9800x3d'), or a category phrase in Portuguese ('ssd nvme', 'teclado mecanico').
- `brands` (array, optional) — Manufacturer names, exactly as `facets.brands` in a previous response spells them ('Kingston', 'ASUS', 'Gigabyte'). Several are OR-ed. A name KaBuM does not know returns zero results, not an error.
- `price_min` (number, optional) — Minimum price in BRL (reais, not cents).
- `price_max` (number, optional) — Maximum price in BRL (reais, not cents).
- `only_offers` (boolean, optional, default false) — Only products KaBuM currently flags as on offer (ssd: 864 → 39 on 2026-09-23).
- `only_kabum` (boolean, optional, default false) — Only KaBuM's own 1P stock, excluding marketplace sellers (ssd: 864 → 103).
- `only_prime` (boolean, optional, default false) — Only products with a KaBuM Prime exclusive price.
- `only_free_shipping` (boolean, optional, default false) — Only products KaBuM highlights as free shipping (ssd: 864 → 88).
- `only_open_box` (boolean, optional, default false) — Only open-box (returned/repackaged) units.
- `attributes` (object, optional) — Category-specific facets, as `{facet name: [values]}` taken verbatim from `facets.attributes` of a previous response — e.g. {"Memória": ["8 GB"]} on graphics cards (447 → 79).
- `sort` (enum, optional, default "relevance") — Result order. KaBuM silently ignores an order it does not know (an unknown value returns its default order with no error), so only the seven it actually applies are accepted here. [one of: relevance, most_searched, price_asc, price_desc, offers, newest, most_rated, brand]
- `page` (integer, optional, default 1) — 1-based page number. `total_results` and `total_pages` in the response tell you how far you can go.
- `limit` (integer, optional, default 20) — Rows per page (1-120). The source serves at most 120 however many you ask for.

**Returns:** products[]{product_id, title, url, brand, category_path, price_brl (card/instalment reference), cash_price_brl (the a-vista PIX/boleto price the site headlines), list_price_brl (pre-campaign reference, only while a campaign runs), old_price_brl, discount_percent, campaign{id, name, starts_at, ends_at, units_available}, installments{count, amount_brl, text}, in_stock, stock, rating_rounded, rating_count, sold_by_kabum, seller{seller_id, name, company, cnpj, state}, free_shipping, is_prime_exclusive, is_open_box, is_pre_order, on_offer, image}, total_results, total_pages, page, limit, sort, facets{brands[], categories[], attributes[], flags[], price_range}

**Example request body:**
```json
{
  "query": "ssd nvme"
}
```

### POST https://api.reefapi.com/kabum/v1/category — 2 credits
Walk one KaBuM! category without a keyword — the way to build a price database for a whole department. Takes the category's URL path (`hardware/placa-de-video-vga`), supports the same filters and sorts as `search`, and returns the source's own breadcrumb so you know exactly which shelf you are reading.

**Parameters:**
- `category` (string, required) — Category path as it appears in a kabum.com.br URL: 'hardware', 'hardware/placa-de-video-vga' or 'hardware/placa-de-video-vga/placa-de-video-amd'. A full kabum.com.br category URL is accepted too. Read a product's `category_slugs` to discover valid paths.
- `brands` (array, optional) — Manufacturer names, exactly as `facets.brands` in a previous response spells them ('Kingston', 'ASUS', 'Gigabyte'). Several are OR-ed. A name KaBuM does not know returns zero results, not an error.
- `price_min` (number, optional) — Minimum price in BRL (reais, not cents).
- `price_max` (number, optional) — Maximum price in BRL (reais, not cents).
- `only_offers` (boolean, optional, default false) — Only products KaBuM currently flags as on offer (ssd: 864 → 39 on 2026-09-23).
- `only_kabum` (boolean, optional, default false) — Only KaBuM's own 1P stock, excluding marketplace sellers (ssd: 864 → 103).
- `only_prime` (boolean, optional, default false) — Only products with a KaBuM Prime exclusive price.
- `only_free_shipping` (boolean, optional, default false) — Only products KaBuM highlights as free shipping (ssd: 864 → 88).
- `only_open_box` (boolean, optional, default false) — Only open-box (returned/repackaged) units.
- `attributes` (object, optional) — Category-specific facets, as `{facet name: [values]}` taken verbatim from `facets.attributes` of a previous response — e.g. {"Memória": ["8 GB"]} on graphics cards (447 → 79).
- `sort` (enum, optional, default "relevance") — Result order. KaBuM silently ignores an order it does not know (an unknown value returns its default order with no error), so only the seven it actually applies are accepted here. [one of: relevance, most_searched, price_asc, price_desc, offers, newest, most_rated, brand]
- `page` (integer, optional, default 1) — 1-based page number. `total_results` and `total_pages` in the response tell you how far you can go.
- `limit` (integer, optional, default 20) — Rows per page (1-120). The source serves at most 120 however many you ask for.

**Returns:** products[] (same shape as search), breadcrumb[]{id, name, path}, total_results, total_pages, page, limit, sort, category, facets{…}

**Example request body:**
```json
{
  "category": "hardware/placa-de-video-vga"
}
```

### POST https://api.reefapi.com/kabum/v1/product — 1 credit
One product in full: both prices, the exact PIX price and EVERY instalment plan KaBuM offers (boleto, PIX, credit card 1-12x, NuPay) with the real amount per plan, live stock, the unrounded rating, the marketplace seller with its company name and CNPJ when it is not KaBuM's own stock, the spec sheet parsed into sections, warranty, weight and the Anatel/Inmetro codes. Two upstream calls are merged into this one answer.

**Parameters:**
- `product_id` (string, required) — The numeric KaBuM product code (459144) or a kabum.com.br/produto/... URL. Every search row returns it.
- `include_specs` (boolean, optional, default true) — Fetch the spec sheet, the unrounded rating and the regulatory codes (one extra upstream call, ~12 KB). Turn it off for a price-only read.

**Returns:** product{…every search field…, rating, rating_rounded, pix_price_brl, payment_options[]{method, label, plans[]{installments, amount_brl, total_brl, interest_free, discount_percent, terms}}, specifications[]{name, values[]}, description, summary_ai, warranty, weight_grams, anatel_code, inmetro_code, limit_per_order, category_ids, category_slugs, images[], cross_sell_ids[], bought_together_ids[]}

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

### POST https://api.reefapi.com/kabum/v1/products — 1 credit
Up to 20 products in ONE upstream call: both prices, the instalment plan, stock, rating and seller for each. This is how a catalogue of thousands is re-priced every morning without spending a call per product. Ids KaBuM no longer serves are simply absent and listed in `missing`.

**Parameters:**
- `product_ids` (array, required) — Up to 20 KaBuM product codes or product URLs. Accepts a JSON array or a comma-separated string. The source returns at most 20 rows per call and silently drops the rest, so more than that is rejected here instead.

**Returns:** products[] (same shape as search, without description/specs), requested, returned, missing[]

**Example request body:**
```json
{
  "product_ids": [
    459144,
    1027061
  ]
}
```

### POST https://api.reefapi.com/kabum/v1/suggest — 1 credit
What KaBuM's own search box suggests for a prefix — the phrases Brazilian shoppers actually type, straight from the site's autocomplete. ~200 bytes a call, so it is the cheap way to expand a keyword list before searching.

**Parameters:**
- `query` (string, required) — A partial search phrase, at least 2 characters. KaBuM rejects a single character.

**Returns:** suggestions[] (plain strings), query

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

### POST https://api.reefapi.com/kabum/v1/deals — 3 credits
The products inside one of KaBuM's running campaigns (its 'promoção' pages). Same rows as `search`, with the campaign's own title. KaBuM publishes no campaign index, so the slugs that answered when this engine was built are listed on the parameter.

**Parameters:**
- `campaign` (enum, optional, default "HARDWAREKABUM") — Which campaign to read. An unknown slug returns NOT_FOUND — KaBuM publishes no campaign index, so these are the ones verified live. [one of: HARDWAREKABUM, COMPUTADORKABUM, perifericoskabum, MUNDOGAMER, ESPACOGAMER]
- `brands` (array, optional) — Manufacturer names, exactly as `facets.brands` in a previous response spells them ('Kingston', 'ASUS', 'Gigabyte'). Several are OR-ed. A name KaBuM does not know returns zero results, not an error.
- `price_min` (number, optional) — Minimum price in BRL (reais, not cents).
- `price_max` (number, optional) — Maximum price in BRL (reais, not cents).
- `only_kabum` (boolean, optional, default false) — Only KaBuM's own 1P stock, excluding marketplace sellers (ssd: 864 → 103).
- `sort` (enum, optional, default "relevance") — Result order. KaBuM silently ignores an order it does not know (an unknown value returns its default order with no error), so only the seven it actually applies are accepted here. [one of: relevance, most_searched, price_asc, price_desc, offers, newest, most_rated, brand]
- `page` (integer, optional, default 1) — 1-based page number. `total_results` and `total_pages` in the response tell you how far you can go.
- `limit` (integer, optional, default 20) — Rows per page (1-120). The source serves at most 120 however many you ask for.

**Returns:** products[] (same shape as search), campaign, campaign_title, total_results, total_pages, page, limit, facets{…}

**Example request body:**
```json
{
  "campaign": "HARDWAREKABUM"
}
```

### POST https://api.reefapi.com/kabum/v1/featured — 2 credits
KaBuM's own curated front-page lists: `highlights` (what it is pushing right now) and `releases` (what has just arrived). Same rows as `search`. Useful for catching new SKUs and price moves without knowing a keyword.

**Parameters:**
- `list` (enum, optional, default "highlights") — Which curated list to read. [one of: highlights, releases]
- `brands` (array, optional) — Manufacturer names, exactly as `facets.brands` in a previous response spells them ('Kingston', 'ASUS', 'Gigabyte'). Several are OR-ed. A name KaBuM does not know returns zero results, not an error.
- `price_min` (number, optional) — Minimum price in BRL (reais, not cents).
- `price_max` (number, optional) — Maximum price in BRL (reais, not cents).
- `only_kabum` (boolean, optional, default false) — Only KaBuM's own 1P stock, excluding marketplace sellers (ssd: 864 → 103).
- `sort` (enum, optional, default "relevance") — Result order. KaBuM silently ignores an order it does not know (an unknown value returns its default order with no error), so only the seven it actually applies are accepted here. [one of: relevance, most_searched, price_asc, price_desc, offers, newest, most_rated, brand]
- `page` (integer, optional, default 1) — 1-based page number. `total_results` and `total_pages` in the response tell you how far you can go.
- `limit` (integer, optional, default 20) — Rows per page (1-120). The source serves at most 120 however many you ask for.

**Returns:** products[] (same shape as search), list, total_results, total_pages, page, limit, facets{…}

**Example request body:**
```json
{
  "list": "highlights"
}
```

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