# Wine — 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 wines on Wine.com to discover detailed information including pricing, ratings, and product metadata across thousands of selections. Find top-rated wines, browse current sales, and access comprehensive details on any wine to make informed purchasing decisions.

**Category:** E-commerce | **Website:** [wine.com/](https://wine.com/) | **Docs:** [parse.bot/marketplace/7b4f453a-6ad8-47e9-ba18-79bf2467d49d/wine-com-api](https://parse.bot/marketplace/7b4f453a-6ad8-47e9-ba18-79bf2467d49d/wine-com-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-wine-com-api-7b4f453a/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_top_rated_wines

Retrieve wines sorted by rating descending from the Wine Shop category. Returns the same paginated format as list_wines, ordered so top-rated wines appear first.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wine-com-api-7b4f453a/get_top_rated_wines \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### get_wine_detail

Retrieve full detail for a single wine by its numeric product ID. Returns the matching wine with all professional critic scores, community ratings, full description, images, and metadata. The numeric product ID can be found in wine URLs on wine.com (e.g. the '330988' in wine.com/product/laurent-perrier-la-cuvee-brut/330988).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Numeric product ID of the wine (e.g. '330988'). Found in wine.com product page URLs. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wine-com-api-7b4f453a/get_wine_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>"}'
```

### get_wines_on_sale

Retrieve wines sorted by savings amount descending from the Wine Shop category. Returns the same paginated format as list_wines, ordered so wines with the biggest discounts appear first.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wine-com-api-7b4f453a/get_wines_on_sale \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### list_wines

Browse wines with filtering and sorting. Returns a paginated list of wines within a category. Category ID 7155 is the default for the full Wine Shop. Supports filtering by wine attributes and sorting by popularity, rating, or savings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | integer | No | Wine category ID. 7155 is the Wine Shop (all wines). |
| `filters` | string | No | Filter string for narrowing results (e.g. '7155-124' for red wines). |
| `page` | integer | No | Page number for pagination. |
| `sort` | string | No | Sort order for results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wine-com-api-7b4f453a/list_wines \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<integer>","filters":"<string>","page":"<integer>","sort":"<string>"}'
```

### search_wines

Search for wines by keyword across Wine.com's catalog. Returns a paginated list of wines matching the search term with pricing, professional reviews, community ratings, and images. Results are sorted by the specified sort order.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `query` | string | Yes | Search term for wine name, producer, region, or other attributes (e.g. 'Pinot Noir', 'Chateau', 'Barolo'). |
| `sort` | string | No | Sort order for results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wine-com-api-7b4f453a/search_wines \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>","sort":"<string>"}'
```