# Lista Mercadolivre — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and browse products from Mercado Livre Brazil, view detailed pricing and offers, and explore categories to find daily deals and product information. Get comprehensive product details including specifications and current market offers all in one place.

**Category:** Marketplaces | **Website:** [lista.mercadolivre.com.br/](https://lista.mercadolivre.com.br/) | **Docs:** [parse.bot/marketplace/f6d31e6c-77e5-4f34-9aa0-df71418a9c4f/lista-mercadolivre-com-br-api](https://parse.bot/marketplace/f6d31e6c-77e5-4f34-9aa0-df71418a9c4f/lista-mercadolivre-com-br-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-lista-mercadolivre-com-br-api-f6d31e6c/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_listing_details

Fetch details of a single product listing including sold units (sales).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_id` | string | Yes | Mercado Livre Item ID or URL |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-lista-mercadolivre-com-br-api-f6d31e6c/get_listing_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"item_id":"<string>"}'
```

### get_lowest_price_item

Find the lowest-priced item matching a keyword within the Joias e Relógios (MLB3937) category on the Ofertas page. Useful for price comparison and deal-hunting within jewelry and watches. Returns the single cheapest matching item or null if no matches found.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | No | Keyword to filter items by name within the Joias e Relógios category (e.g. relogio, colar, brinco). Defaults to 'relogio' when omitted. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-lista-mercadolivre-com-br-api-f6d31e6c/get_lowest_price_item \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### get_recent_listings

Retrieve all current listings from the Ofertas (deals) page. All items on the page are active promotions. The days parameter is accepted for compatibility but does not filter results — the page only shows currently active deals.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `days` | integer | No | Accepted for compatibility but does not filter results; all returned listings are current active deals. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-lista-mercadolivre-com-br-api-f6d31e6c/get_recent_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"days":"<integer>"}'
```

### search_listings

Search for product listings on the Mercado Livre Brazil 'Ofertas' (deals) page. Without a category_id, returns all current deals. The query parameter filters results locally by name within the fetched listings. Returns matching listings with pricing, discount, and store information, plus aggregate statistics (total count, average price). Single-page response containing all matching deals in the selected category.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | Mercado Livre category ID to filter deals (e.g. MLB3937 for Joias e Relógios, MLB1648 for Informática). When omitted, returns all deals from the main Ofertas page. |
| `query` | string | No | Keyword to filter results by product name (case-insensitive local filter applied after fetching the category page). Works best when combined with category_id. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-lista-mercadolivre-com-br-api-f6d31e6c/search_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","query":"<string>"}'
```