# Wine — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/wine/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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.beta.paywithlocus.com/api/wrapped/credits/wine/get-top-rated-wines \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/wine/get-wine-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/wine/get-wines-on-sale \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/wine/list-wines \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/wine/search-wines \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>","sort":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.