# Vivino — 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 discover wines across thousands of options while accessing detailed information like user reviews, pricing, winery profiles, and food pairing recommendations. Explore grape varieties, compare wines side-by-side, and find the perfect bottle based on ratings and availability.

**Category:** Food & Dining | **Website:** [vivino.com/](https://vivino.com/) | **Docs:** [parse.bot/marketplace/45a5703b-2808-49ff-b11b-d7714c3b5dcd/vivino-com-api](https://parse.bot/marketplace/45a5703b-2808-49ff-b11b-d7714c3b5dcd/vivino-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/vivino/`
**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

### Explore wines

Browse the wine catalog ordered by popularity. Returns a paginated list of wines without any search filter applied. Useful for discovering trending or highly-rated wines.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (1-indexed). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/vivino/explore-wines \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### Get food pairings

Find wines related to a food keyword by searching the wine index. Results include wines whose names or associated metadata (winery name, vintage name) match the food term. Useful for discovering wines branded or associated with specific foods.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `food_name` | string | Yes | Food name to find wine pairings for (e.g. 'steak', 'chicken', 'pasta'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/vivino/get-food-pairings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"food_name":"<string>"}'
```

### Get wine details

Retrieve full details for a single wine by its numeric ID or SEO slug. Returns wine name, region, winery, vintages, description, grape IDs, food pairing IDs, alcohol percentage, and aggregate statistics. Exactly one of wine_id or wine_slug must be provided.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `wine_id` | string | No | Vivino wine ID (e.g. '1135067'). Either wine_id or wine_slug is required. |
| `wine_slug` | string | No | Wine SEO slug (e.g. 'reserve-malbec'). Either wine_id or wine_slug is required. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/vivino/get-wine-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"wine_id":"<string>","wine_slug":"<string>"}'
```

### Get winery details

Retrieve full details for a winery by its SEO slug. Searches the wine index and extracts winery metadata including name, region, statistics, description, website, and winemaker. Falls back to the first matching result's winery if no exact slug match is found.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `winery_slug` | string | Yes | Winery SEO slug (e.g. 'penfolds', 'opus-one', 'casillero-del-diablo'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/vivino/get-winery-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"winery_slug":"<string>"}'
```

### Search wineries

Search for wineries by name. Searches the wine index and extracts unique wineries from matching results. Each winery includes name, region, statistics, description, and website.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (0-indexed). |
| `query` | string | Yes | Winery name to search for. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/vivino/search-wineries \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

### Search wines

Full-text search over Vivino's wine catalog. Matches wine name, grape variety, region, and winery name. Returns paginated results ordered by relevance with full wine details including name, region, winery, vintages, ratings, and description.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Max results per page. |
| `page` | integer | No | Page number (0-indexed). |
| `query` | string | Yes | Search keyword (wine name, grape variety, region, winery, etc.). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/vivino/search-wines \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","query":"<string>"}'
```

## Next steps

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