← Back to Developer Hub

AI Agent Skill for Vivino API

Universal skill definition for Claude, OpenAI Codex, OpenClaw, Hermes, Pi, Cursor, and other AI agents to search wines, fetch community ratings, reviews, and vintages.

Raw SKILL.md Download ZIP

Claude Anthropic

Upload ZIP to Customize > Skills or copy into your .claude/skills/ directory.

OpenAI Codex OpenAI

Save to ~/.agents/skills/vivino-api/ or reference in agent system prompts.

OpenClaw Agent CLI

Import directly from raw URL or install to ~/.openclaw/skills/vivino-api/.

Hermes & Others Universal

Standard markdown skill format compatible with Hermes, Pi, Cursor, and custom LLM tools.

Universal agent format: This skill is structured with standard YAML frontmatter and OpenAPI endpoints. You can copy the raw markdown, fetch it via URL, or download the multi-agent ZIP archive.

---
name: vivino-api
description: Search and fetch wine details, community ratings, review counts, prices, and vintage information from the Vivino API using Claude, Codex, OpenClaw, Hermes, or other AI agents.
---

# Vivino API Skill for AI Agents (Claude, Codex, OpenClaw, Hermes & more)

Use this skill when you need to query wine information, community ratings, review counts, average prices, and vintage details from the Vivino API in any LLM assistant, coding agent, or autonomous agent workflow (Claude, Codex, OpenClaw, Hermes, Cursor, Windsurf, Pi, etc.).

## Base Guidance

- **Primary Endpoint:** `GET /api/wine/search?q={query}`
- **Authentication:** Bearer token
  - `Authorization: Bearer {YOUR_API_KEY}`
  - `Accept: application/json`
- **Base URL:** `https://wine.mediashare.ro`
- **OpenAPI Schema:** `/openapi/direct.json`

## Example Request

```bash
curl -G 'https://wine.mediashare.ro/api/wine/search' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  --data-urlencode 'q=Purcari Malbec 2020'
```

## Response Fields

The API responds with normalized wine information:

- `id` (integer) - Internal database identifier
- `name` (string) - Wine / cuvée name
- `winery` (string) - Producer / winery name
- `year` (integer|null) - Vintage year
- `score` (float) - Community average score (1.0 - 5.0)
- `reviews` (integer) - Total number of community ratings
- `url` (string) - Direct Vivino wine webpage
- `grapes` (string|null) - Grape varietal(s)
- `type` (integer|null) - Wine classification (1: Red, 2: White, 3: Sparkling, 4: Rosé, 7: Dessert, 24: Fortified)
- `avg_price` (string|null) - Computed average price
- `currency` (string|null) - Currency (e.g. `EUR`, `USD`, `RON`)

## Agent Usage & Best Practices

1. **Constructing Search Queries:**
   - Include producer, wine name, and vintage year when known (e.g., `Chateau Margaux 2015`, `Catena Zapata Malbec 2019`).
   - For general exploration, pass the brand or appellation (e.g., `Tignanello Antinori`).

2. **Output Shaping for Users:**
   - Always highlight the wine name, winery, vintage, rating (e.g., `⭐ 4.3/5 based on 250 reviews`), average price if available, and provide the direct Vivino URL for further reading.

3. **Multi-Agent Setup:**
   - **Claude**: Upload the skill ZIP via *Customize > Skills* or place in `.claude/skills/`.
   - **Codex / Hermes / Pi**: Save this file as `SKILL.md` under `~/.agents/skills/vivino-api/SKILL.md`.
   - **OpenClaw**: Place under `~/.openclaw/skills/vivino-api/SKILL.md` or fetch raw markdown.

1. Download / Copy Download vivino-api-skill.zip or copy SKILL.md from this page.

2. Install in Agent Place in your agent's skill directory (e.g. ~/.agents/skills/, ~/.openclaw/skills/, or Claude Skills).

3. Search Wines Set your Bearer API key and ask your assistant to search wines or fetch ratings.