# MercadoLibre API — product search, prices, deals, reviews and category browse across MercadoLibre's Latin American marketplaces (Argentina, Mexico, Brazil, Chile, Colombia and more); no API key, multi-country.

> MercadoLibre's live deals feed (Ofertas del día) — discounted listing cards with current and previous price, discount %, star rating + review count, seller (+official-store flag), shipping and brand. Multi-country, paginated, optional minimum-discount filter. Note: this is the site-wide daily-deals browse — it is NOT keyword-filtered.
> ReefAPI engine `mercadolibre` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/mercadolibre/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 or blocked calls are free.
- **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 /mercadolibre/v1/deals — 1 credit
MercadoLibre's live deals feed (Ofertas del día) — discounted listing cards with current and previous price, discount %, star rating + review count, seller (+official-store flag), shipping and brand. Multi-country, paginated, optional minimum-discount filter. Note: this is the site-wide daily-deals browse — it is NOT keyword-filtered.

**Parameters:**
- `site_id` (enum, optional, default "MLA") — MercadoLibre country site. MLA=Argentina, MLM=Mexico, MLB=Brazil, MLC=Chile, MCO=Colombia, MLU=Uruguay, MPE=Peru, MEC=Ecuador, MRD=Dominican Republic, etc. Prices and currency are per-country. [one of: MLA, MLM, MLB, MLC, MCO, MLU, MPE, MLV, MBO, MPY, MEC, MRD, MCR, MGT, MPA, MHN, MNI, MSV]
- `page` (integer, optional, default 1) — Page to start from (1, 2, 3 …; ~48 deals/page).
- `max_pages` (integer, optional, default 1) — How many consecutive pages to fetch + merge in one call (1–10, ~48 items/page; deduped).
- `min_discount` (integer, optional, default 0) — Only items discounted at least this % off the previous price.
- `sort` (enum, optional, default "discount") — Order the returned deals. [one of: discount, price_asc, price_desc, rating]

**Returns:** items[]{item_id, product_id, title, permalink, price{current, previous, currency, discount_label, installments_text}, discount_pct, reviews_summary{rating_average, total}, seller, is_official_store, shipping_text, brand, deal_label} + total_results (meta.pagination for paging)

**Example request body:**
```json
{
  "site_id": "MLA"
}
```

### POST /mercadolibre/v1/category_items — 1 credit
Products listed in a MercadoLibre category — title, price (current/previous/discount), rating, product link and picture. Pass a category_id (it's resolved to the category's /c/ landing page). The query-keyword search is login-walled on MercadoLibre, so this is the bare-DC way to retrieve real products for a category.

**Parameters:**
- `category_id` (string, required) — MercadoLibre category ID (e.g. MLA1051 = Celulares y Teléfonos in Argentina). Discover IDs with the `category` action.
- `site_id` (enum, optional, default "MLA") — MercadoLibre country site. MLA=Argentina, MLM=Mexico, MLB=Brazil, MLC=Chile, MCO=Colombia, MLU=Uruguay, MPE=Peru, MEC=Ecuador, MRD=Dominican Republic, etc. Prices and currency are per-country. [one of: MLA, MLM, MLB, MLC, MCO, MLU, MPE, MLV, MBO, MPY, MEC, MRD, MCR, MGT, MPA, MHN, MNI, MSV]
- `sort` (enum, optional, default "relevance") — Order the returned items. [one of: relevance, price_asc, price_desc, rating]
- `min_price` (number, optional) — Only items at or above this price (site currency).
- `max_price` (number, optional) — Only items at or below this price (site currency).

**Returns:** items[]{item_id, product_id, title, permalink, price{current, previous, currency, discount_label}, reviews_summary{rating_average, total}, picture} + category{id, name}

**Example request body:**
```json
{
  "category_id": "MLA1051"
}
```

### POST /mercadolibre/v1/reviews — 1 credit
Buyer reviews for a catalog product — full review text, rating and date, paginated to gather ALL reviews in one call + a derived star distribution and average. Works across countries.

**Parameters:**
- `product_id` (string, required) — MercadoLibre catalog product ID (the ML…id in a /p/<id> URL — e.g. MLA1027172677). Get it from a search item's product_id.
- `site_id` (enum, optional, default "MLA") — MercadoLibre country site. MLA=Argentina, MLM=Mexico, MLB=Brazil, MLC=Chile, MCO=Colombia, MLU=Uruguay, MPE=Peru, MEC=Ecuador, MRD=Dominican Republic, etc. Prices and currency are per-country. [one of: MLA, MLM, MLB, MLC, MCO, MLU, MPE, MLV, MBO, MPY, MEC, MRD, MCR, MGT, MPA, MHN, MNI, MSV]
- `page` (integer, optional, default 1) — Review page to start from (20 reviews/page).
- `max_pages` (integer, optional, default 5) — How many review pages to gather in one call (1–25, 20/page → up to 500 reviews). Stops early when reviews run out.

**Returns:** reviews[]{id, rating, text, date, variant} + summary{count, average_rating, distribution{1..5}} (meta.pagination for paging)

### POST /mercadolibre/v1/suggest — 1 credit
Search-term autocomplete — what MercadoLibre suggests as a shopper types.

**Parameters:**
- `query` (string, required) — Partial search text to complete.
- `site_id` (enum, optional, default "MLA") — MercadoLibre country site. MLA=Argentina, MLM=Mexico, MLB=Brazil, MLC=Chile, MCO=Colombia, MLU=Uruguay, MPE=Peru, MEC=Ecuador, MRD=Dominican Republic, etc. Prices and currency are per-country. [one of: MLA, MLM, MLB, MLC, MCO, MLU, MPE, MLV, MBO, MPY, MEC, MRD, MCR, MGT, MPA, MHN, MNI, MSV]

**Returns:** suggestions[]{query, match_start, match_end}

### POST /mercadolibre/v1/category — 1 credit
Browse the MercadoLibre category tree — a category's name, total item count, full path from root and its direct child subcategories. Drill down via children[].id; use `category_items` to retrieve the products within a category.

**Parameters:**
- `category_id` (string, required) — MercadoLibre category ID (starts with the site prefix, e.g. MLA1051 = Celulares y Teléfonos in Argentina, MLB1051 in Brazil). Drill down via this action's children[].id.

**Returns:** category{id, name, total_items, permalink, path_from_root[], children[]{id, name, total_items}}

**Example request body:**
```json
{
  "category_id": "MLA1051"
}
```

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